Folder

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "#/components/schemas/Folder",
  "title": "Folder",
  "type": "object",
  "x-box-resource-id": "folder",
  "x-box-variant": "standard",
  "description": "A standard representation of a folder, as returned from any\nfolder API endpoints by default",
  "allOf": [
    {
      "$ref": "#/components/schemas/Folder--Mini"
    },
    {
      "properties": {
        "created_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true,
          "description": "The date and time when the folder was created. This value may\nbe `null` for some folders such as the root folder or the trash\nfolder.",
          "example": "2012-12-12T10:53:43-08:00"
        },
        "modified_at": {
          "type": "string",
          "format": "date-time",
          "description": "The date and time when the folder was last updated. This value may\nbe `null` for some folders such as the root folder or the trash\nfolder.",
          "example": "2012-12-12T10:53:43-08:00",
          "nullable": true
        },
        "description": {
          "allOf": [
            {
              "type": "string",
              "description": "The optional description of this folder",
              "maxLength": 256,
              "example": "Legal contracts for the new ACME deal",
              "nullable": false
            },
            {
              "nullable": false
            }
          ]
        },
        "size": {
          "type": "integer",
          "format": "int64",
          "description": "The folder size in bytes.\n\nBe careful parsing this integer as its\nvalue can get very large.",
          "example": 629644,
          "nullable": false
        },
        "path_collection": {
          "allOf": [
            {
              "title": "Path collection",
              "description": "A list of parent folders for an item.",
              "type": "object",
              "required": [
                "total_count",
                "entries"
              ],
              "properties": {
                "total_count": {
                  "description": "The number of folders in this list.",
                  "example": 1,
                  "type": "integer",
                  "format": "int64",
                  "nullable": false
                },
                "entries": {
                  "type": "array",
                  "description": "The parent folders for this item",
                  "nullable": false,
                  "items": {
                    "$ref": "#/components/schemas/Folder--Mini"
                  }
                }
              }
            },
            {
              "description": "The tree of folders that this folder is contained in,\nstarting at the root."
            },
            {
              "nullable": false
            }
          ]
        },
        "created_by": {
          "allOf": [
            {
              "$ref": "#/components/schemas/User--Mini"
            },
            {
              "description": "The user who created this folder"
            },
            {
              "nullable": false
            }
          ]
        },
        "modified_by": {
          "allOf": [
            {
              "$ref": "#/components/schemas/User--Mini"
            },
            {
              "description": "The user who last modified this folder."
            },
            {
              "nullable": false
            }
          ]
        },
        "trashed_at": {
          "type": "string",
          "format": "date-time",
          "description": "The time at which this folder was put in the trash.",
          "example": "2012-12-12T10:53:43-08:00",
          "nullable": true
        },
        "purged_at": {
          "type": "string",
          "format": "date-time",
          "description": "The time at which this folder is expected to be purged\nfrom the trash.",
          "example": "2012-12-12T10:53:43-08:00",
          "nullable": true
        },
        "content_created_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true,
          "description": "The date and time at which this folder was originally\ncreated.",
          "example": "2012-12-12T10:53:43-08:00"
        },
        "content_modified_at": {
          "type": "string",
          "format": "date-time",
          "nullable": true,
          "description": "The date and time at which this folder was last updated.",
          "example": "2012-12-12T10:53:43-08:00"
        },
        "owned_by": {
          "allOf": [
            {
              "$ref": "#/components/schemas/User--Mini"
            },
            {
              "description": "The user who owns this folder."
            },
            {
              "nullable": false
            }
          ]
        },
        "shared_link": {
          "allOf": [
            {
              "title": "Shared link",
              "description": "Shared links provide direct, read-only access to files or folder on Box.\n\nShared links with open access level allow anyone with the URL\nto access the item, while shared links with company or collaborators access\nlevels can only be accessed by appropriately authenticated Box users.",
              "type": "object",
              "required": [
                "url",
                "accessed",
                "effective_access",
                "effective_permission",
                "is_password_enabled",
                "download_count",
                "preview_count"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "format": "url",
                  "description": "The URL that can be used to access the item on Box.\n\nThis URL will display the item in Box's preview UI where the file\ncan be downloaded if allowed.\n\nThis URL will continue to work even when a custom `vanity_url`\nhas been set for this shared link.",
                  "example": "https://www.box.com/s/vspke7y05sb214wjokpk",
                  "nullable": false
                },
                "download_url": {
                  "type": "string",
                  "format": "url",
                  "x-box-premium-feature": true,
                  "description": "A URL that can be used to download the file. This URL can be used in\na browser to download the file. This URL includes the file\nextension so that the file will be saved with the right file type.\n\nThis property will be `null` for folders.",
                  "example": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
                  "nullable": true
                },
                "vanity_url": {
                  "type": "string",
                  "format": "url",
                  "description": "The \"Custom URL\" that can also be used to preview the item on Box.  Custom\nURLs can only be created or modified in the Box Web application.",
                  "example": "https://acme.app.box.com/v/my_url/",
                  "nullable": true
                },
                "vanity_name": {
                  "type": "string",
                  "description": "The custom name of a shared link, as used in the `vanity_url` field.",
                  "example": "my_url",
                  "nullable": true
                },
                "access": {
                  "type": "string",
                  "description": "The access level for this shared link.\n\n* `open` - provides access to this item to anyone with this link\n* `company` - only provides access to this item to people the same company\n* `collaborators` - only provides access to this item to people who are\n   collaborators on this item\n\nIf this field is omitted when creating the shared link, the access level\nwill be set to the default access level specified by the enterprise admin.",
                  "enum": [
                    "open",
                    "company",
                    "collaborators"
                  ],
                  "example": "open",
                  "nullable": false
                },
                "effective_access": {
                  "type": "string",
                  "description": "The effective access level for the shared link. This can be a more\nrestrictive access level than the value in the `access` field when the\nenterprise settings restrict the allowed access levels.",
                  "enum": [
                    "open",
                    "company",
                    "collaborators"
                  ],
                  "example": "company",
                  "nullable": false
                },
                "effective_permission": {
                  "type": "string",
                  "description": "The effective permissions for this shared link.\nThese result in the more restrictive combination of\nthe share link permissions and the item permissions set\nby the administrator, the owner, and any ancestor item\nsuch as a folder.",
                  "enum": [
                    "can_edit",
                    "can_download",
                    "can_preview",
                    "no_access"
                  ],
                  "example": "can_download",
                  "nullable": false
                },
                "unshared_at": {
                  "type": "string",
                  "format": "date-time",
                  "description": "The date and time when this link will be unshared. This field can only be\nset by users with paid accounts.",
                  "example": "2018-04-13T13:53:23-07:00",
                  "nullable": true
                },
                "is_password_enabled": {
                  "type": "boolean",
                  "description": "Defines if the shared link requires a password to access the item.",
                  "example": true,
                  "nullable": false
                },
                "permissions": {
                  "type": "object",
                  "description": "Defines if this link allows a user to preview, edit, and download an item.\nThese permissions refer to the shared link only and\ndo not supersede permissions applied to the item itself.",
                  "required": [
                    "can_download",
                    "can_preview",
                    "can_edit"
                  ],
                  "properties": {
                    "can_download": {
                      "type": "boolean",
                      "example": true,
                      "nullable": false,
                      "description": "Defines if the shared link allows for the item to be downloaded. For\nshared links on folders, this also applies to any items in the folder.\n\nThis value can be set to `true` when the effective access level is\nset to `open` or `company`, not `collaborators`."
                    },
                    "can_preview": {
                      "type": "boolean",
                      "example": true,
                      "nullable": false,
                      "description": "Defines if the shared link allows for the item to be previewed.\n\nThis value is always `true`. For shared links on folders this also\napplies to any items in the folder."
                    },
                    "can_edit": {
                      "type": "boolean",
                      "example": false,
                      "nullable": false,
                      "description": "Defines if the shared link allows for the item to be edited.\n\nThis value can only be `true` if `can_download` is also `true` and if\nthe item has a type of `file`."
                    }
                  }
                },
                "download_count": {
                  "type": "integer",
                  "example": 3,
                  "description": "The number of times this item has been downloaded.",
                  "nullable": false
                },
                "preview_count": {
                  "type": "integer",
                  "example": 3,
                  "description": "The number of times this item has been previewed.",
                  "nullable": false
                }
              }
            },
            {
              "description": "The shared link for this folder. This will be\n`null` if no shared link has been created for this\nfolder."
            }
          ],
          "nullable": true
        },
        "folder_upload_email": {
          "type": "object",
          "nullable": true,
          "properties": {
            "access": {
              "type": "string",
              "example": "open",
              "nullable": false,
              "enum": [
                "open",
                "collaborators"
              ],
              "description": "When this parameter has been set, users can email files\nto the email address that has been automatically\ncreated for this folder.\n\nTo create an email address, set this property either when\ncreating or updating the folder.\n\nWhen set to `collaborators`, only emails from registered email\naddresses for collaborators will be accepted. This includes\nany email aliases a user might have registered.\n\nWhen set to `open` it will accept emails from any email\naddress."
            },
            "email": {
              "description": "The optional upload email address for this folder.",
              "type": "string",
              "format": "email",
              "example": "[email protected]",
              "nullable": false
            }
          }
        },
        "parent": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Folder--Mini"
            },
            {
              "description": "The optional folder that this folder is located within.\n\nThis value may be `null` for some folders such as the\nroot folder or the trash folder."
            }
          ],
          "nullable": true
        },
        "item_status": {
          "type": "string",
          "description": "Defines if this item has been deleted or not.\n\n* `active` when the item has is not in the trash\n* `trashed` when the item has been moved to the trash but not deleted\n* `deleted` when the item has been permanently deleted.",
          "enum": [
            "active",
            "trashed",
            "deleted"
          ],
          "nullable": false,
          "example": "active"
        },
        "item_collection": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Items"
            },
            {
              "description": "A page of the items that are in the folder.\n\nThis field can only be requested when querying a folder's\ninformation, not when querying a folder's items."
            },
            {
              "nullable": false
            }
          ]
        }
      }
    }
  ]
}