BObox
Folders

Create folder

Changed on

Creates a new empty folder within the specified parent folder.

post/folders

Request

  • Base URL
    https://api.box.com/2.0
  • URL
    https://api.box.com/2.0/folders
  • Auth
    OAuth 2
    Authorization code: https://account.box.com/api/oauth2/authorize
    Token URL: https://api.box.com/oauth2/token

Query parameters

fieldsstring[]

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.

Request body

namestring required

The name for the new 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.

sync_state'synced' | 'not_synced' | 'partially_synced'

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.

Example request

{
  "name": "New Folder",
  "parent": {
    "id": "0"
  },
  "folder_upload_email": {
    "access": "open"
  },
  "sync_state": "synced"
}

Response

Returns a folder object.

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

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

etagstring nullable

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.

type'folder' required

The value will always be folder.

sequence_idstring

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.

namestring

The name of the folder.

created_atstring date-time nullable

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.

modified_atstring date-time nullable

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.

descriptionstring

The optional description of this folder.

sizeinteger

The folder size in bytes.

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

trashed_atstring date-time nullable

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

purged_atstring date-time nullable

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

content_created_atstring date-time nullable

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

content_modified_atstring date-time nullable

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

item_status'active' | 'trashed' | 'deleted'

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.
sync_state'synced' | 'not_synced' | 'partially_synced'

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.

has_collaborationsboolean

Specifies if this folder has any other collaborators.

tagsstring[]

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.

can_non_owners_inviteboolean

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

is_externally_ownedboolean

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

metadataobject

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.

is_collaboration_restricted_to_enterpriseboolean

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

allowed_shared_link_access_levelsstring[]

The shared link access levels the authenticated user is allowed to use when creating or updating a shared link for this folder.

The list depends on item policy and user authorization. For some folders, like the root folder, this is always empty as sharing is not allowed at that level.

allowed_invitee_rolesstring[]

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

is_accessible_via_shared_linkboolean

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

can_non_owners_view_collaboratorsboolean

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.

is_associated_with_app_itemboolean

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 response

{
  "id": "12345",
  "etag": "1",
  "type": "folder",
  "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",
        "etag": "1",
        "type": "folder",
        "sequence_id": "3",
        "name": "Contracts"
      }
    ]
  },
  "created_by": {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "ceo@example.com"
  },
  "modified_by": {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "ceo@example.com"
  },
  "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": "ceo@example.com"
  },
  "shared_link": {
    "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
    "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",
    "effective_access": "company",
    "effective_permission": "can_download",
    "unshared_at": "2018-04-13T13:53:23-07:00",
    "is_password_enabled": true,
    "permissions": {
      "can_download": true,
      "can_preview": true
    },
    "download_count": 3,
    "preview_count": 3,
    "one_time_passcode": {
      "mode": "allowlist",
      "allowlist": [
        {
          "type": "email",
          "value": "alice@example.com",
          "created_at": "2026-05-19T12:00:00Z",
          "created_by": {
            "id": "11446498",
            "type": "user"
          }
        },
        {
          "type": "domain",
          "value": "example.com",
          "created_at": "2026-05-19T12:00:00Z",
          "created_by": {
            "id": "11446498",
            "type": "user"
          }
        }
      ]
    }
  },
  "folder_upload_email": {
    "access": "open",
    "email": "upload.Contracts.asd7asd@u.box.com"
  },
  "parent": {
    "id": "12345",
    "etag": "1",
    "type": "folder",
    "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",
        "etag": "1",
        "type": "file",
        "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": [
            {
              "id": "12345",
              "etag": "1",
              "type": "folder",
              "sequence_id": "3",
              "name": "Contracts"
            }
          ]
        },
        "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": "ceo@example.com"
        },
        "modified_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "owned_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "shared_link": {
          "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
          "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",
          "effective_access": "company",
          "effective_permission": "can_download",
          "unshared_at": "2018-04-13T13:53:23-07:00",
          "is_password_enabled": true,
          "permissions": {
            "can_download": true,
            "can_preview": true
          },
          "download_count": 3,
          "preview_count": 3,
          "one_time_passcode": {
            "mode": "allowlist",
            "allowlist": [
              {
                "type": "email",
                "value": "alice@example.com",
                "created_at": "2026-05-19T12:00:00Z",
                "created_by": {
                  "id": "11446498",
                  "type": "user"
                }
              },
              {
                "type": "domain",
                "value": "example.com",
                "created_at": "2026-05-19T12:00:00Z",
                "created_by": {
                  "id": "11446498",
                  "type": "user"
                }
              }
            ]
          }
        },
        "parent": {
          "id": "12345",
          "etag": "1",
          "type": "folder",
          "sequence_id": "3",
          "name": "Contracts"
        },
        "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,
          "can_apply_watermark": true
        },
        "tags": [
          "approved"
        ],
        "lock": {
          "id": "11446498",
          "type": "lock",
          "created_by": {
            "id": "11446498",
            "type": "user",
            "name": "Aaron Levie",
            "login": "ceo@example.com"
          },
          "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": "12345",
                "etag": "1",
                "type": "folder",
                "sequence_id": "3",
                "name": "Contracts"
              }
            }
          ],
          "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,
        "collections": [
          {
            "id": "11446498",
            "type": "collection",
            "name": "Favorites",
            "collection_type": "favorites"
          }
        ],
        "is_download_available": true,
        "download_url": "https://dl.boxcloud.com/d/1/example_token/download",
        "authenticated_download_url": "https://api.box.com/2.0/files/12345/content",
        "allowed_shared_link_access_levels": [
          "open"
        ]
      }
    ]
  },
  "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,
    "can_apply_watermark": 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,
  "collections": [
    {
      "id": "11446498",
      "type": "collection",
      "name": "Favorites",
      "collection_type": "favorites"
    }
  ]
}

Changes

  • c4d5303fa5c3Revision changes
    • warning

      added the new unprocessable_entity enum value to the response property for the response status

    • warning

      added the new unprocessable_entity enum value to the response property for the response status

    • warning

      added the new unprocessable_entity enum value to the response property for the response status

    • warning

      added the new unprocessable_entity enum value to the response property for the response status

    • warning

      added the new unprocessable_entity enum value to the response property for the response status

    • info

      added the optional property / to the response with the status

    • info

      added subschema #1 subschema #2 to the / response property allOf list for the response status

    • info

      added subschema #1 subschema #2 subschema #3 to the /// response property allOf list for the response status

    • info

      added subschema #2 subschema #3 to the //// response property allOf list for the response status

    • info

      removed subschema #1 subschema #2 from the / response property allOf list for the response status

    • info

      removed subschema #1 subschema #2 subschema #3 from the /// response property allOf list for the response status

    • info

      removed subschema #2 subschema #3 from the //// response property allOf list for the response status

    • info

      added the required property //// to the response with the status