Skip to main content
PUT
/
folders
/
{folder_id}
cURL
curl -i -X PUT "https://api.box.com/2.0/folders/4353455" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "name": "New folder name"
     }'
{
  "id": "12345",
  "type": "folder",
  "etag": "1",
  "sequence_id": "3",
  "name": "Contracts",
  "created_at": "2012-12-12T10:53:43-08:00",
  "modified_at": "2012-12-12T10:53:43-08:00",
  "description": "Legal contracts for the new ACME deal",
  "size": 629644,
  "path_collection": {
    "total_count": 1,
    "entries": [
      {
        "id": "12345",
        "type": "folder",
        "etag": "1",
        "sequence_id": "3",
        "name": "Contracts"
      }
    ]
  },
  "created_by": {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "[email protected]"
  },
  "modified_by": {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "[email protected]"
  },
  "trashed_at": "2012-12-12T10:53:43-08:00",
  "purged_at": "2012-12-12T10:53:43-08:00",
  "content_created_at": "2012-12-12T10:53:43-08:00",
  "content_modified_at": "2012-12-12T10:53:43-08:00",
  "owned_by": {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "[email protected]"
  },
  "shared_link": {
    "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
    "effective_access": "company",
    "effective_permission": "can_download",
    "is_password_enabled": true,
    "download_count": 3,
    "preview_count": 3,
    "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
    "vanity_url": "https://acme.app.box.com/v/my_url/",
    "vanity_name": "my_url",
    "access": "open",
    "unshared_at": "2018-04-13T13:53:23-07:00",
    "permissions": {
      "can_download": true,
      "can_preview": true,
      "can_edit": false
    }
  },
  "folder_upload_email": {
    "access": "open",
    "email": "[email protected]"
  },
  "parent": {
    "id": "12345",
    "type": "folder",
    "etag": "1",
    "sequence_id": "3",
    "name": "Contracts"
  },
  "item_status": "active",
  "item_collection": {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "total_count": 5000,
    "offset": 2000,
    "order": [
      {
        "by": "type",
        "direction": "ASC"
      }
    ],
    "entries": [
      {
        "id": "12345",
        "type": "file",
        "etag": "1",
        "sequence_id": "3",
        "name": "Contract.pdf",
        "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
        "file_version": {
          "id": "12345",
          "type": "file_version",
          "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
        },
        "description": "Contract for Q1 renewal",
        "size": 629644,
        "path_collection": {
          "total_count": 1,
          "entries": [
            "<unknown>"
          ]
        },
        "created_at": "2012-12-12T10:53:43-08:00",
        "modified_at": "2012-12-12T10:53:43-08:00",
        "trashed_at": "2012-12-12T10:53:43-08:00",
        "purged_at": "2012-12-12T10:53:43-08:00",
        "content_created_at": "2012-12-12T10:53:43-08:00",
        "content_modified_at": "2012-12-12T10:53:43-08:00",
        "created_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "[email protected]"
        },
        "modified_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "[email protected]"
        },
        "owned_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "[email protected]"
        },
        "shared_link": {
          "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
          "effective_access": "company",
          "effective_permission": "can_download",
          "is_password_enabled": true,
          "download_count": 3,
          "preview_count": 3,
          "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
          "vanity_url": "https://acme.app.box.com/v/my_url/",
          "vanity_name": "my_url",
          "access": "open",
          "unshared_at": "2018-04-13T13:53:23-07:00",
          "permissions": {
            "can_download": true,
            "can_preview": true,
            "can_edit": false
          }
        },
        "parent": "<unknown>",
        "item_status": "active",
        "version_number": "1",
        "comment_count": 10,
        "permissions": {
          "can_delete": true,
          "can_download": true,
          "can_invite_collaborator": true,
          "can_rename": true,
          "can_set_share_access": true,
          "can_share": true,
          "can_annotate": true,
          "can_comment": true,
          "can_preview": true,
          "can_upload": true,
          "can_view_annotations_all": true,
          "can_view_annotations_self": true
        },
        "tags": [
          "approved"
        ],
        "lock": {
          "id": "11446498",
          "type": "lock",
          "created_by": {
            "id": "11446498",
            "type": "user",
            "name": "Aaron Levie",
            "login": "[email protected]"
          },
          "created_at": "2012-12-12T10:53:43-08:00",
          "expired_at": "2012-12-12T10:53:43-08:00",
          "is_download_prevented": true,
          "app_type": "office_wopiplus"
        },
        "extension": "pdf",
        "is_package": true,
        "expiring_embed_link": {
          "access_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
          "expires_in": 3600,
          "token_type": "bearer",
          "restricted_to": [
            {
              "scope": "item_download",
              "object": {
                "id": "<unknown>",
                "type": "<unknown>",
                "etag": "<unknown>",
                "sequence_id": "<unknown>",
                "name": "<unknown>"
              }
            }
          ],
          "url": "https://cloud.app.box.com/preview/expiring_embed/..."
        },
        "watermark_info": {
          "is_watermarked": true
        },
        "is_accessible_via_shared_link": true,
        "allowed_invitee_roles": [
          "editor"
        ],
        "is_externally_owned": true,
        "has_collaborations": true,
        "metadata": {
          "enterprise_27335": {
            "marketingCollateral": {
              "$canEdit": true,
              "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
              "$parent": "folder_59449484661",
              "$scope": "enterprise_27335",
              "$template": "marketingCollateral",
              "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
              "$typeVersion": 2,
              "$version": 1
            }
          }
        },
        "expires_at": "2012-12-12T10:53:43-08:00",
        "representations": {
          "entries": [
            {
              "content": {
                "url_template": "https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567"
              },
              "info": {
                "url": "https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048"
              },
              "properties": {
                "dimensions": "2048x2048",
                "paged": "true",
                "thumb": "true"
              },
              "representation": "png",
              "status": {
                "state": "success"
              }
            }
          ]
        },
        "classification": {
          "name": "Top Secret",
          "definition": "Content that should not be shared outside the company.",
          "color": "#FF0000"
        },
        "uploader_display_name": "Ellis Wiggins",
        "disposition_at": "2012-12-12T10:53:43-08:00",
        "shared_link_permission_options": [
          "can_preview"
        ],
        "is_associated_with_app_item": true
      }
    ]
  },
  "sync_state": "synced",
  "has_collaborations": true,
  "permissions": {
    "can_delete": true,
    "can_download": true,
    "can_invite_collaborator": true,
    "can_rename": true,
    "can_set_share_access": true,
    "can_share": true,
    "can_upload": true
  },
  "tags": [
    "approved"
  ],
  "can_non_owners_invite": true,
  "is_externally_owned": true,
  "metadata": {
    "enterprise_27335": {
      "marketingCollateral": {
        "$canEdit": true,
        "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
        "$parent": "folder_59449484661",
        "$scope": "enterprise_27335",
        "$template": "marketingCollateral",
        "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
        "$typeVersion": 2,
        "$version": 1
      }
    }
  },
  "is_collaboration_restricted_to_enterprise": true,
  "allowed_shared_link_access_levels": [
    "open"
  ],
  "allowed_invitee_roles": [
    "editor"
  ],
  "watermark_info": {
    "is_watermarked": true
  },
  "is_accessible_via_shared_link": true,
  "can_non_owners_view_collaborators": true,
  "classification": {
    "name": "Top Secret",
    "definition": "Content that should not be shared outside the company.",
    "color": "#FF0000"
  },
  "is_associated_with_app_item": true
}
This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.Learn more about Box SDK versioning strategy.

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Headers

​
if-match
string

Ensures this item hasn't recently changed before making changes.

Pass in the item's last observed etag value into this header and the endpoint will fail with a 412 Precondition Failed if it has changed since.

Path Parameters

​
folder_id
string
required

The unique identifier that represent a folder.

The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL https://*.app.box.com/folder/123 the folder_id is 123.

The root folder of a Box account is always represented by the ID 0.

Query Parameters

​
fields
string[]

A comma-separated list of attributes to include in the response. This can be used to request fields that are not normally returned in a standard response.

Be aware that specifying this parameter will have the effect that none of the standard fields are returned in the response unless explicitly specified, instead only fields for the mini representation are returned, additional to the fields requested.

Body

application/json
​
name
string

The optional new name for this folder.

The following restrictions to folder names apply: names containing non-printable ASCII characters, forward and backward slashes (/, \), names with trailing spaces, and names . and .. are not allowed.

Folder names must be unique within their parent folder. The name check is case-insensitive, so a folder named New Folder cannot be created in a parent folder that already contains a folder named new folder.

Example:

"New Folder"

​
description
string

The optional description of this folder.

Maximum string length: 256
Example:

"Legal contracts for the new ACME deal"

​
sync_state
enum<string>

Specifies whether a folder should be synced to a user's device or not. This is used by Box Sync (discontinued) and is not used by Box Drive.

Available options:
synced,
not_synced,
partially_synced
Example:

"synced"

​
can_non_owners_invite
boolean

Specifies if users who are not the owner of the folder can invite new collaborators to the folder.

Example:

true

​
parent
object

The parent folder for this folder. Use this to move the folder or to restore it out of the trash.

​
shared_link
object

Enables the creation of a shared link for a folder.

​
folder_upload_email
Folder upload email · object

Setting this object enables the upload email address.

This email address can be used by users to directly upload files directly to the folder via email.

Setting the value to null will disable the email address.

​
tags
string[]

The tags for this item. These tags are shown in the Box web app and mobile apps next to an item.

To add or remove a tag, retrieve the item's current tags, modify them, and then update this field.

There is a limit of 100 tags per item, and 10,000 unique tags per enterprise.

Required array length: 1 - 100 elements
Example:
["approved"]
​
is_collaboration_restricted_to_enterprise
boolean

Specifies if new invites to this folder are restricted to users within the enterprise. This does not affect existing collaborations.

Example:

true

​
collections
Reference · object[] | null

An array of collections to make this folder a member of. Currently we only support the favorites collection.

To get the ID for a collection, use the List all collections endpoint.

Passing an empty array [] or null will remove the folder from all collections.

​
can_non_owners_view_collaborators
boolean

Restricts collaborators who are not the owner of this folder from viewing other collaborations on this folder.

It also restricts non-owners from inviting new collaborators.

When setting this field to false, it is required to also set can_non_owners_invite_collaborators to false if it has not already been set.

Example:

true

Response

Returns a folder object for the updated folder

Not all available fields are returned by default. Use the fields query parameter to explicitly request any specific fields.

If the user is moving folders with a large number of items in all of their descendants, the call will be run asynchronously. If the operation is not completed within 10 minutes, the user will receive a 200 OK response, and the operation will continue running.

A full representation of a folder, as can be returned from any folder API endpoints by default.

​
id
string
required

The unique identifier that represent a folder.

The ID for any folder can be determined by visiting a folder in the web application and copying the ID from the URL. For example, for the URL https://*.app.box.com/folders/123 the folder_id is 123.

Example:

"12345"

​
type
enum<string>
required

The value will always be folder.

Available options:
folder
Example:

"folder"

​
etag
string | null

The HTTP etag of this folder. This can be used within some API endpoints in the If-Match and If-None-Match headers to only perform changes on the folder if (no) changes have happened.

Example:

"1"

​
sequence_id
string | null

A numeric identifier that represents the most recent user event that has been applied to this item.

This can be used in combination with the GET /events-endpoint to filter out user events that would have occurred before this identifier was read.

An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the sequence_id in the event is smaller than or equal to the sequence_id in the originally fetched resource.

Example:

"3"

​
name
string

The name of the folder.

Example:

"Contracts"

​
created_at
string<date-time> | null

The date and time when the folder was created. This value may be null for some folders such as the root folder or the trash folder.

Example:

"2012-12-12T10:53:43-08:00"

​
modified_at
string<date-time> | null

The date and time when the folder was last updated. This value may be null for some folders such as the root folder or the trash folder.

Example:

"2012-12-12T10:53:43-08:00"

​
description
string

The optional description of this folder.

Maximum string length: 256
Example:

"Legal contracts for the new ACME deal"

​
size
integer<int64>

The folder size in bytes.

Be careful parsing this integer as its value can get very large.

Example:

629644

​
path_collection
Path collection · object

The tree of folders that this folder is contained in, starting at the root.

​
created_by
User (Mini) · object

The user who created this folder.

​
modified_by
User (Mini) · object

The user who last modified this folder.

​
trashed_at
string<date-time> | null

The time at which this folder was put in the trash.

Example:

"2012-12-12T10:53:43-08:00"

​
purged_at
string<date-time> | null

The time at which this folder is expected to be purged from the trash.

Example:

"2012-12-12T10:53:43-08:00"

​
content_created_at
string<date-time> | null

The date and time at which this folder was originally created.

Example:

"2012-12-12T10:53:43-08:00"

​
content_modified_at
string<date-time> | null

The date and time at which this folder was last updated.

Example:

"2012-12-12T10:53:43-08:00"

​
owned_by
User (Mini) · object

The user who owns this folder.

​
shared_link
Shared link · object

The shared link for this folder. This will be null if no shared link has been created for this folder.

​
folder_upload_email
object

The folder_upload_email parameter is not null if one of the following options is true:

  • The Allow uploads to this folder via email and the Only allow email uploads from collaborators in this folder are enabled for a folder in the Admin Console, and the user has at least Upload permissions granted.

  • The Allow uploads to this folder via email setting is enabled for a folder in the Admin Console, and the Only allow email uploads from collaborators in this folder setting is deactivated (unchecked).

If the conditions are not met, the parameter will have the following value: folder_upload_email: null.

​
parent
Folder (Mini) · object

The optional folder that this folder is located within.

This value may be null for some folders such as the root folder or the trash folder.

​
item_status
enum<string>

Defines if this item has been deleted or not.

  • active when the item has is not in the trash
  • trashed when the item has been moved to the trash but not deleted
  • deleted when the item has been permanently deleted.
Available options:
active,
trashed,
deleted
Example:

"active"

​
item_collection
Items · object

A page of the items that are in the folder.

This field can only be requested when querying a folder's information, not when querying a folder's items.

​
sync_state
enum<string>

Specifies whether a folder should be synced to a user's device or not. This is used by Box Sync (discontinued) and is not used by Box Drive.

Available options:
synced,
not_synced,
partially_synced
Example:

"synced"

​
has_collaborations
boolean

Specifies if this folder has any other collaborators.

Example:

true

​
permissions
object

Describes the permissions that the current user has for this folder.

​
tags
string[]

The tags for this item. These tags are shown in the Box web app and mobile apps next to an item.

To add or remove a tag, retrieve the item's current tags, modify them, and then update this field.

There is a limit of 100 tags per item, and 10,000 unique tags per enterprise.

Required array length: 1 - 100 elements
Example:
["approved"]
​
can_non_owners_invite
boolean

Specifies if users who are not the owner of the folder can invite new collaborators to the folder.

Example:

true

​
is_externally_owned
boolean

Specifies if this folder is owned by a user outside of the authenticated enterprise.

Example:

true

​
metadata
Item metadata instances · object

An object containing the metadata instances that have been attached to this folder.

Each metadata instance is uniquely identified by its scope and templateKey. There can only be one instance of any metadata template attached to each folder. Each metadata instance is nested within an object with the templateKey as the key, which again itself is nested in an object with the scope as the key.

Example:
{
  "enterprise_27335": {
    "marketingCollateral": {
      "$canEdit": true,
      "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
      "$parent": "folder_59449484661",
      "$scope": "enterprise_27335",
      "$template": "marketingCollateral",
      "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
      "$typeVersion": 2,
      "$version": 1
    }
  }
}
​
is_collaboration_restricted_to_enterprise
boolean

Specifies if new invites to this folder are restricted to users within the enterprise. This does not affect existing collaborations.

Example:

true

​
allowed_shared_link_access_levels
enum<string>[]

A list of access levels that are available for this folder.

For some folders, like the root folder, this will always be an empty list as sharing is not allowed at that level.

Available options:
open,
company,
collaborators
Example:
["open"]
​
allowed_invitee_roles
enum<string>[]

A list of the types of roles that user can be invited at when sharing this folder.

Available options:
editor,
viewer,
previewer,
uploader,
previewer uploader,
viewer uploader,
co-owner
Example:
["editor"]
​
watermark_info
object

Details about the watermark applied to this folder.

​
is_accessible_via_shared_link
boolean

Specifies if the folder can be accessed with the direct shared link or a shared link to a parent folder.

Example:

true

​
can_non_owners_view_collaborators
boolean

Specifies if collaborators who are not owners of this folder are restricted from viewing other collaborations on this folder.

It also restricts non-owners from inviting new collaborators.

Example:

true

​
classification
object

Details about the classification applied to this folder.

​
is_associated_with_app_item
boolean

This field will return true if the folder or any ancestor of the folder is associated with at least one app item. Note that this will return true even if the context user does not have access to the app item(s) associated with the folder.

Example:

true