#%RAML 0.8 --- title: Box.com API version: "2.0" baseUri: https://api.box.com/{version}/ securitySchemes: - oauth_2_0: description: | The Box API uses OAuth 2 for authentication. An authorization header containing a valid access_token must be included in every request. type: OAuth 2.0 describedBy: headers: Authorization: description: | Used to send a valid OAuth 2 access token. Do not use together with the "access_token" query string parameter. type: string queryParameters: access_token: description: | Used to send a valid OAuth 2 access token. Do not use together with the "Authorization" header type: string settings: authorizationUri: https://www.box.com/api/oauth2/authorize accessTokenUri: https://www.box.com/api/oauth2/token authorizationGrants: [ code, token ] securedBy: [ oauth_2_0 ] mediaType: application/json resourceTypes: - base: get: securedBy: [ oauth_2_0: { scopes: [ ADMINISTRATOR ] }] headers: If-None-Match?: description: | If-None-Match headers ensure that you don’t retrieve unnecessary data if you already have the most current version on-hand. type: string On-Behalf-Of?: description: | Used for enterprise administrators to make API calls on behalf of their managed users. To enable this functionality, please contact us with your API key. type: string responses: 200?: description: | The request has succeeded. The information returned with the response is dependent on the method used in the request. 202?: description: | The request has been accepted for processing, but the processing has not been completed. 302?: description: "Found. The requested resource resides temporarily under a different URI." 304?: description: | Not Modified. If the client has performed a conditional GET request and access is allowed, but the document has not been modified 400: description: | Bad Request. The request could not be understood by the server due to malformed syntax. 401: description: "Unauthorized. The request requires user authentication." 404: description: "Not Found. The server has not found anything matching the Request-URI." 429: description: "Your application is sending too many simultaneous requests." 500: description: "We couldn't return the representation due to an internal server error." 507: description: | Insufficient Storage. The server is unable to store the representation needed to complete the request post?: headers: If-Match?: description: | If-Match header let you ensure that your app only alters files/folders on Box if you have the current version. type: string Content-MD5: description: The SHA1 hash of the file. type: string responses: 201?: description: | The request has been fulfilled and resulted in a new resource being created. 403: description: | Forbidden. The server understood the request, but is refusing to fulfill it. 405: description: | Method Not Allowed. The method specified in the Request-Line is not allowed for the resource identified by the Request-URI. 409: description: | Conflict. The request could not be completed due to a conflict with the current state of the resource. Often happened because of file names duplication. 429: description: "Your application is sending too many simultaneous requests." put?: headers: If-Match?: description: | If-Match header let you ensure that your app only alters files/folders on Box if you have the current version. type: string responses: 200?: description: | The request has succeeded. The information returned with the response is dependent on the method used in the request. 429: description: "Your application is sending too many simultaneous requests." delete?: headers: If-Match?: description: | If-Match header let you ensure that your app only alters files/folders on Box if you have the current version. type: string responses: 204?: description: | "No Content. The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation." 404: description: "The file is not in the trash." 412: description: | Precondition Failed. The precondition given in one or more of the request-header fields evaluated to false when it was tested on the server. 429: description: "Your application is sending too many simultaneous requests." traits: - secured: queryParameters: <>: description: A valid <> is required paged: queryParameters: numPages: description: The number of pages to return, not to exceed <> /folders: type: base post: is: [ secured: { tokenName: access_token }, paged: { maxPages: 10 } ] description: | Used to create a new empty folder. The new folder will be created inside of the specified parent folder body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "name": { "description": "The desired name for the folder.", "type": "string" }, "parent": { "description": "The parent folder.", "type": "object" }, "id": { "description": "The ID of the parent folder.", "type": "string" } }, "required": [ "name", "parent", "id" ] } responses: 200: body: example: | { "type": "folder", "id": "11446498", "sequence_id": "1", "etag": "1", "name": "Pictures", "created_at": "2012-12-12T10:53:43-08:00", "modified_at": "2012-12-12T11:15:04-08:00", "description": "Some pictures I took", "size": 629644, "path_collection": { "total_count": 1, "entries": [ { "type": "folder", "id": "0", "sequence_id": null, "etag": null, "name": "All Files" } ] }, "created_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "modified_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "owned_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "shared_link": { "url": "https://www.box.com/s/vspke7y05sb214wjokpk", "download_url": "https://www.box.com/shared/static/vspke7y05sb214wjokpk", "vanity_url": null, "is_password_enabled": false, "unshared_at": null, "download_count": 0, "preview_count": 0, "access": "open", "permissions": { "can_download": true, "can_preview": true } }, "folder_upload_email": { "access": "open", "email": "upload.Picture.k13sdz1@u.box.com" }, "parent": { "type": "folder", "id": "0", "sequence_id": null, "etag": null, "name": "All Files" }, "item_status": "active", "item_collection": { "total_count": 0, "entries": [], "offset": 0, "limit": 100 } } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "type": { "description": "For folders is 'folder'.", "type": "string" }, "id": { "description": "The folder’s ID.", "type": "string" }, "sequence_id": { "description": "A unique ID for use with the /events endpoint.", "type": "string" }, "etag": { "description": "A unique string identifying the version of this folder.", "type": "string" }, "name": { "description": "The name of the folder.", "type": "string" }, "created_at": { "description": "The time the folder was created.", "type": "timestamp" }, "modified_at": { "description": "The time the folder or its contents were last modified.", "type": "timestamp" }, "description": { "description": "The description of the folder.", "type": "string" }, "size": { "description": "The folder size in bytes.", "type": "integer" }, "path_collection": { "paths": { "properties": { "total_count": { "type": "integer" }, "entries": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "description": "Array of entries.", "type": "array" }, "type": "object" }, "description": "Array of paths.", "type": "array" }, "created_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who created this folder.", "type": "object" }, "modified_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who last modified this folder.", "type": "object" }, "owned_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who owns this folder.", "type": "object" }, "shared_link": { "properties": { "url": { "type": "string" }, "download_url": { "type": "string" }, "vanity_url": { "type": "string" }, "is_password_enabled": { "type": "boolean" }, "unshared_at": { "type": "string" }, "download_count": { "type": "integer" }, "preview_count": { "type": "integer" }, "access": { "type": "string" }, "permissions": { "properties": { "can_download": { "type": "boolean" }, "can_preview": { "type": "boolean" } } } }, "description": "The shared link for this folder.", "type": "object" }, "folder_upload_email": { "properties": { "access": { "type": "string" }, "email": { "type": "string" } }, "description": "The upload email address for this folder.", "type": "object" }, "parent": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" } }, "description": "The folder that contains this one.", "type": "object" }, "item_status": { "description": "Whether this item is deleted or not.", "type": "string" }, "item_collection": { "items": { "properties": { "total_count": { "type": "integer" }, "entries": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "sha1": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "description": "Array of entries", "type": "array" }, "type": "object" }, "description": "A collection of mini file and folder objects contained in this folder.", "type": "array" }, "sync_state": { "description": "Whether this folder will be synced by the Box sync clients or not.", "required": false, "enum": [ "synced", "not_synced", "partially_synced" ] }, "has_collaborations": { "description": "Whether this folder has any collaborators.", "required": false, "type": "boolean" } }, "type": "object" } /{folderId}: type: base uriParameters: folderId: description: | The ID of the parent folder type: string get: description: | Retrieves the full metadata about a folder, including information about when it was last updated as well as the files and folders contained in it. The root folder of a Box account is always represented by the id "0". responses: 200: body: example: | { "type": "folder", "id": "11446498", "sequence_id": "1", "etag": "1", "name": "Pictures", "created_at": "2012-12-12T10:53:43-08:00", "modified_at": "2012-12-12T11:15:04-08:00", "description": "Some pictures I took", "size": 629644, "path_collection": { "total_count": 1, "entries": [ { "type": "folder", "id": "0", "sequence_id": null, "etag": null, "name": "All Files" } ] }, "created_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "modified_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "owned_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "shared_link": { "url": "https://www.box.com/s/vspke7y05sb214wjokpk", "download_url": "https://www.box.com/shared/static/vspke7y05sb214wjokpk", "vanity_url": null, "is_password_enabled": false, "unshared_at": null, "download_count": 0, "preview_count": 0, "access": "open", "permissions": { "can_download": true, "can_preview": true } }, "folder_upload_email": { "access": "open", "email": "upload.Picture.k13sdz1@u.box.com" }, "parent": { "type": "folder", "id": "0", "sequence_id": null, "etag": null, "name": "All Files" }, "item_status": "active", "item_collection": { "total_count": 1, "entries": [ { "type": "file", "id": "5000948880", "sequence_id": "3", "etag": "3", "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc", "name": "tigers.jpeg" } ], "offset": 0, "limit": 100 } } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "type": { "description": "For files is 'file'", "type": "string" }, "id": { "description": "Box’s unique string identifying this file.", "type": "string" }, "sequence_id": { "description": "A unique ID for use with the /events endpoint.", "type": "string" }, "etag": { "description": "A unique string identifying the version of this file.", "type": "string" }, "sha1": { "description": "The sha1 hash of this file.", "type": "string" }, "name": { "description": "The name of this file.", "type": "string" }, "description": { "description": "The description of this file.", "type": "string" }, "size": { "description": "Size of this file in bytes.", "type": "integer" }, "path_collection": { "paths": { "properties": { "total_count": { "type": "integer" }, "entries": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "description": "Array of entries.", "type": "array" }, "type": "object" }, "description": "The path of folders to this item, starting at the root.", "type": "array" }, "created_at": { "description": "When this file was created on Box’s servers.", "type": "timestamp" }, "modified_at": { "description": "When this file was last updated on the Box servers.", "type": "timestamp" }, "trashed_at": { "description": "When this file was last moved to the trash.", "type": "timestamp" }, "purged_at": { "description": "When this file will be permanently deleted.", "type": "timestamp" }, "content_created_at": { "description": "When the content of this file was created.", "type": "timestamp" }, "content_modified_at": { "description": "When the content of this file was last modified.", "type": "timestamp" }, "created_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who first created file.", "type": "object" }, "modified_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who last updated this file.", "type": "object" }, "owned_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who owns this file.", "type": "object" }, "shared_link": { "properties": { "url": { "type": "string" }, "download_url": { "type": "string" }, "vanity_url": { "type": "string" }, "is_password_enabled": { "type": "boolean" }, "unshared_at": { "type": "string" }, "download_count": { "type": "integer" }, "preview_count": { "type": "integer" }, "access": { "type": "string" }, "permissions": { "properties": { "can_download": { "type": "boolean" }, "can_preview": { "type": "boolean" } } } }, "description": "The shared link object for this file.", "type": "object" }, "parent": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" } }, "description": "The folder this file is contained in.", "type": "object" }, "item_status": { "description": "Whether this item is deleted or not.", "type": "string" }, "version_number": { "description": "Whether this folder will be synced by the Box sync clients or not.", "required": false, "type": "string" }, "comment_count": { "description": "The number of comments on a file", "required": false, "type": "integer" } }, "type": "object" } put: description: | Used to update information about the folder. To move a folder, update the ID of its parent. To enable an email address that can be used to upload files to this folder, update the folder_upload_email attribute. An optional If-Match header can be included to ensure that client only updates the folder if it knows about the latest version. body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "name": { "description": "The desired name for the folder.", "type": "string" }, "parent": { "description": "The parent folder.", "type": "object" }, "id": { "description": "The ID of the parent folder.", "type": "string" }, "description": { "description": "The description of the folder.", "type": "string" }, "shared_link": { "description": "An object representing this item’s shared link and associated permissions.", "type": "object" }, "access": { "description": "The level of access required for this shared link.", "type": [ "open", "company", "collaborators"] }, "unshared_at": { "description": "The day that this link should be disabled at. Timestamps are rounded off to the given day.", "type": "timestamp" } }, "required": [ "name", "parent", "id"] } responses: 200: body: example: | { "type": "folder", "id": "11446498", "sequence_id": "1", "etag": "1", "name": "New Folder Name!", "created_at": "2012-12-12T10:53:43-08:00", "modified_at": "2012-12-12T11:15:04-08:00", "description": "Some pictures I took", "size": 629644, "path_collection": { "total_count": 1, "entries": [ { "type": "folder", "id": "0", "sequence_id": null, "etag": null, "name": "All Files" } ] }, "created_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "modified_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "owned_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "shared_link": { "url": "https://www.box.com/s/vspke7y05sb214wjokpk", "download_url": "https://www.box.com/shared/static/vspke7y05sb214wjokpk", "vanity_url": null, "is_password_enabled": false, "unshared_at": null, "download_count": 0, "preview_count": 0, "access": "open", "permissions": { "can_download": true, "can_preview": true } }, "folder_upload_email": { "access": "open", "email": "upload.Picture.k13sdz1@u.box.com" }, "parent": { "type": "folder", "id": "0", "sequence_id": null, "etag": null, "name": "All Files" }, "item_status": "active", "item_collection": { "total_count": 1, "entries": [ { "type": "file", "id": "5000948880", "sequence_id": "3", "etag": "3", "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc", "name": "tigers.jpeg" } ], "offset": 0, "limit": 100 } } delete: description: | Used to delete a folder. A recursive parameter must be included in order to delete folders that have items inside of them. An optional If-Match header can be included to ensure that client only deletes the folder if it knows about the latest version. queryParameters: recursive: description: Whether to delete this folder if it has items inside of it. type: boolean responses: 204: description: Folder removed. post: description: | Restores an item that has been moved to the trash. Default behavior is to restore the item to the folder it was in before it was moved to the trash. If that parent folder no longer exists or if there is now an item with the same name in that parent folder, the new parent folder and/or new name will need to be included in the request. body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "name": { "description": "The new name for this item.", "type": "string" }, "parent": { "description": "The new parent folder for this item.", "type": "object" }, "id": { "description": "The id of the new parent folder.", "type": "string" } } } responses: 201: description: Item was succesfully created. body: example: | { "type": "folder", "id": "588970022", "sequence_id": "2", "etag": "2", "name": "heloo world", "created_at": "2013-01-15T16:15:27-08:00", "modified_at": "2013-02-07T13:26:00-08:00", "description": "", "size": 0, "path_collection": { "total_count": 1, "entries": [ { "type": "folder", "id": "0", "sequence_id": null, "etag": null, "name": "All Files" } ] }, "created_by": { "type": "user", "id": "181757341", "name": "sean test", "login": "sean+test@box.com" }, "modified_by": { "type": "user", "id": "181757341", "name": "sean test", "login": "sean+test@box.com" }, "trashed_at": null, "purged_at": null, "content_created_at": "2013-01-15T16:15:27-08:00", "content_modified_at": "2013-02-07T13:26:00-08:00", "owned_by": { "type": "user", "id": "181757341", "name": "sean test", "login": "sean+test@box.com" }, "shared_link": null, "folder_upload_email": null, "parent": { "type": "folder", "id": "0", "sequence_id": null, "etag": null, "name": "All Files" }, "item_status": "active" } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "type": { "description": "For files is 'file'", "type": "string" }, "id": { "description": "Box’s unique string identifying this file.", "type": "string" }, "sequence_id": { "description": "A unique ID for use with the /events endpoint.", "type": "string" }, "etag": { "description": "A unique string identifying the version of this file.", "type": "string" }, "sha1": { "description": "The sha1 hash of this file.", "type": "string" }, "name": { "description": "The name of this file.", "type": "string" }, "description": { "description": "The description of this file.", "type": "string" }, "size": { "description": "Size of this file in bytes.", "type": "integer" }, "path_collection": { "paths": { "properties": { "total_count": { "type": "integer" }, "entries": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "description": "Array of entries.", "type": "array" }, "type": "object" }, "description": "The path of folders to this item, starting at the root.", "type": "array" }, "created_at": { "description": "When this file was created on Box’s servers.", "type": "timestamp" }, "modified_at": { "description": "When this file was last updated on the Box servers.", "type": "timestamp" }, "trashed_at": { "description": "When this file was last moved to the trash.", "type": "timestamp" }, "purged_at": { "description": "When this file will be permanently deleted.", "type": "timestamp" }, "content_created_at": { "description": "When the content of this file was created.", "type": "timestamp" }, "content_modified_at": { "description": "When the content of this file was last modified.", "type": "timestamp" }, "created_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who first created file.", "type": "object" }, "modified_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who last updated this file.", "type": "object" }, "owned_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who owns this file.", "type": "object" }, "shared_link": { "properties": { "url": { "type": "string" }, "download_url": { "type": "string" }, "vanity_url": { "type": "string" }, "is_password_enabled": { "type": "boolean" }, "unshared_at": { "type": "string" }, "download_count": { "type": "integer" }, "preview_count": { "type": "integer" }, "access": { "type": "string" }, "permissions": { "properties": { "can_download": { "type": "boolean" }, "can_preview": { "type": "boolean" } } } }, "description": "The shared link object for this file.", "type": "object" }, "parent": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" } }, "description": "The folder this file is contained in.", "type": "object" }, "item_status": { "description": "Whether this item is deleted or not.", "type": "string" }, "version_number": { "description": "Whether this folder will be synced by the Box sync clients or not.", "required": false, "type": "string" }, "comment_count": { "description": "The number of comments on a file", "required": false, "type": "integer" } }, "type": "object" } /copy: type: base post: description: | Used to create a copy of a folder in another folder. The original version of the folder will not be altered. body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "name": { "description": "An optional new name for the folder.", "type": "string" }, "parent": { "description": "Object representing the new location of the folder.", "type": "string" }, "id": { "description": "The ID of the destination folder.", "type": "string" } }, "required": [ "parent", "id" ] } responses: 200: body: example: | { "type": "folder", "id": "11446498", "sequence_id": "1", "etag": "1", "name": "Pictures", "created_at": "2012-12-12T10:53:43-08:00", "modified_at": "2012-12-12T11:15:04-08:00", "description": "Some pictures I took", "size": 629644, "path_collection": { "total_count": 1, "entries": [ { "type": "folder", "id": "0", "sequence_id": null, "etag": null, "name": "All Files" } ] }, "created_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "modified_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "owned_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "shared_link": { "url": "https://www.box.com/s/vspke7y05sb214wjokpk", "download_url": "https://www.box.com/shared/static/vspke7y05sb214wjokpk", "vanity_url": null, "is_password_enabled": false, "unshared_at": null, "download_count": 0, "preview_count": 0, "access": "open", "permissions": { "can_download": true, "can_preview": true } }, "folder_upload_email": { "access": "open", "email": "upload.Picture.k13sdz1@u.box.com" }, "parent": { "type": "folder", "id": "0", "sequence_id": null, "etag": null, "name": "All Files" }, "item_status": "active", "item_collection": { "total_count": 1, "entries": [ { "type": "file", "id": "5000948880", "sequence_id": "3", "etag": "3", "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc", "name": "tigers.jpeg" } ], "offset": 0, "limit": 100 } } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "type": { "description": "For folders is 'folder'.", "type": "string" }, "id": { "description": "The folder’s ID.", "type": "string" }, "sequence_id": { "description": "A unique ID for use with the /events endpoint.", "type": "string" }, "etag": { "description": "A unique string identifying the version of this folder.", "type": "string" }, "name": { "description": "The name of the folder.", "type": "string" }, "created_at": { "description": "The time the folder was created.", "type": "timestamp" }, "modified_at": { "description": "The time the folder or its contents were last modified.", "type": "timestamp" }, "description": { "description": "The description of the folder.", "type": "string" }, "size": { "description": "The folder size in bytes.", "type": "integer" }, "path_collection": { "paths": { "properties": { "total_count": { "type": "integer" }, "entries": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "description": "Array of entries.", "type": "array" }, "type": "object" }, "description": "Array of paths.", "type": "array" }, "created_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who created this folder.", "type": "object" }, "modified_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who last modified this folder.", "type": "object" }, "owned_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who owns this folder.", "type": "object" }, "shared_link": { "properties": { "url": { "type": "string" }, "download_url": { "type": "string" }, "vanity_url": { "type": "string" }, "is_password_enabled": { "type": "boolean" }, "unshared_at": { "type": "string" }, "download_count": { "type": "integer" }, "preview_count": { "type": "integer" }, "access": { "type": "string" }, "permissions": { "properties": { "can_download": { "type": "boolean" }, "can_preview": { "type": "boolean" } } } }, "description": "The shared link for this folder.", "type": "object" }, "folder_upload_email": { "properties": { "access": { "type": "string" }, "email": { "type": "string" } }, "description": "The upload email address for this folder.", "type": "object" }, "parent": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" } }, "description": "The folder that contains this one.", "type": "object" }, "item_status": { "description": "Whether this item is deleted or not.", "type": "string" }, "item_collection": { "items": { "properties": { "total_count": { "type": "integer" }, "entries": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "sha1": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "description": "Array of entries", "type": "array" }, "type": "object" }, "description": "A collection of mini file and folder objects contained in this folder.", "type": "array" }, "sync_state": { "description": "Whether this folder will be synced by the Box sync clients or not.", "required": false, "enum": [ "synced", "not_synced", "partially_synced" ] }, "has_collaborations": { "description": "Whether this folder has any collaborators.", "required": false, "type": "boolean" } }, "type": "object" } /trash: type: base get: description: | Retrieves an item that has been moved to the trash. The full item will be returned, including information about when the it was moved to the trash. responses: 200: body: example: | { "type": "folder", "id": "588970022", "sequence_id": "1", "etag": "1", "name": "heloo world", "created_at": "2013-01-15T16:15:27-08:00", "modified_at": "2013-01-17T13:48:23-08:00", "description": "", "size": 0, "path_collection": { "total_count": 1, "entries": [ { "type": "folder", "id": "1", "sequence_id": null, "etag": null, "name": "Trash" } ] }, "created_by": { "type": "user", "id": "181757341", "name": "sean test", "login": "sean+test@box.com" }, "modified_by": { "type": "user", "id": "181757341", "name": "sean test", "login": "sean+test@box.com" }, "trashed_at": "2013-02-07T12:53:32-08:00", "purged_at": "2013-03-09T12:53:32-08:00", "content_created_at": "2013-01-15T16:15:27-08:00", "content_modified_at": "2013-01-17T13:48:23-08:00", "owned_by": { "type": "user", "id": "181757341", "name": "sean test", "login": "sean+test@box.com" }, "shared_link": null, "folder_upload_email": null, "parent": { "type": "folder", "id": "0", "sequence_id": null, "etag": null, "name": "All Files" }, "item_status": "trashed" } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "type": { "description": "For files is 'file'", "type": "string" }, "id": { "description": "Box’s unique string identifying this file.", "type": "string" }, "sequence_id": { "description": "A unique ID for use with the /events endpoint.", "type": "string" }, "etag": { "description": "A unique string identifying the version of this file.", "type": "string" }, "sha1": { "description": "The sha1 hash of this file.", "type": "string" }, "name": { "description": "The name of this file.", "type": "string" }, "description": { "description": "The description of this file.", "type": "string" }, "size": { "description": "Size of this file in bytes.", "type": "integer" }, "path_collection": { "paths": { "properties": { "total_count": { "type": "integer" }, "entries": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "description": "Array of entries.", "type": "array" }, "type": "object" }, "description": "The path of folders to this item, starting at the root.", "type": "array" }, "created_at": { "description": "When this file was created on Box’s servers.", "type": "timestamp" }, "modified_at": { "description": "When this file was last updated on the Box servers.", "type": "timestamp" }, "trashed_at": { "description": "When this file was last moved to the trash.", "type": "timestamp" }, "purged_at": { "description": "When this file will be permanently deleted.", "type": "timestamp" }, "content_created_at": { "description": "When the content of this file was created.", "type": "timestamp" }, "content_modified_at": { "description": "When the content of this file was last modified.", "type": "timestamp" }, "created_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who first created file.", "type": "object" }, "modified_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who last updated this file.", "type": "object" }, "owned_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who owns this file.", "type": "object" }, "shared_link": { "properties": { "url": { "type": "string" }, "download_url": { "type": "string" }, "vanity_url": { "type": "string" }, "is_password_enabled": { "type": "boolean" }, "unshared_at": { "type": "string" }, "download_count": { "type": "integer" }, "preview_count": { "type": "integer" }, "access": { "type": "string" }, "permissions": { "properties": { "can_download": { "type": "boolean" }, "can_preview": { "type": "boolean" } } } }, "description": "The shared link object for this file.", "type": "object" }, "parent": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" } }, "description": "The folder this file is contained in.", "type": "object" }, "item_status": { "description": "Whether this item is deleted or not.", "type": "string" }, "version_number": { "description": "Whether this folder will be synced by the Box sync clients or not.", "required": false, "type": "string" }, "comment_count": { "description": "The number of comments on a file", "required": false, "type": "integer" } }, "type": "object" } delete: description: | Permanently deletes an item that is in the trash. The item will no longer exist in Box. This action cannot be undone. responses: 204: description: Item successfully removed. /items: type: base get: description: | Retrieves the files and/or folders contained within this folder without any other metadata about the folder. queryParameters: fields: description: Attribute(s) to include in the response type: string limit: description: The number of items to return type: integer default: 100 maximum: 1000 offset: description: The item at which to begin the response type: integer default: 0 responses: 200: body: example: | { "total_count": 24, "entries": [ { "type": "folder", "id": "192429928", "sequence_id": "1", "etag": "1", "name": "Stephen Curry Three Pointers" }, { "type": "file", "id": "818853862", "sequence_id": "0", "etag": "0", "name": "Warriors.jpg" } ], "offset": 0, "limit": 2, "order": [ { "by": "type", "direction": "ASC" }, { "by": "name", "direction": "ASC" } ] } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "total_count": { "type": "integer" }, "entries": [ { "properties": { "type": { "description": "For files is 'file'", "type": "string" }, "id": { "description": "Box’s unique string identifying this file.", "type": "string" }, "sequence_id": { "description": "A unique ID for use with the /events endpoint.", "type": "string" }, "etag": { "description": "A unique string identifying the version of this file.", "type": "string" }, "sha1": { "description": "The sha1 hash of this file.", "type": "string" }, "name": { "description": "The name of this file.", "type": "string" }, "description": { "description": "The description of this file.", "type": "string" }, "size": { "description": "Size of this file in bytes.", "type": "integer" }, "path_collection": { "paths": { "properties": { "total_count": { "type": "integer" }, "entries": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "description": "Array of entries.", "type": "array" }, "type": "object" }, "description": "The path of folders to this item, starting at the root.", "type": "array" }, "created_at": { "description": "When this file was created on Box’s servers.", "type": "timestamp" }, "modified_at": { "description": "When this file was last updated on the Box servers.", "type": "timestamp" }, "trashed_at": { "description": "When this file was last moved to the trash.", "type": "timestamp" }, "purged_at": { "description": "When this file will be permanently deleted.", "type": "timestamp" }, "content_created_at": { "description": "When the content of this file was created.", "type": "timestamp" }, "content_modified_at": { "description": "When the content of this file was last modified.", "type": "timestamp" }, "created_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who first created file.", "type": "object" }, "modified_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who last updated this file.", "type": "object" }, "owned_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who owns this file.", "type": "object" }, "shared_link": { "properties": { "url": { "type": "string" }, "download_url": { "type": "string" }, "vanity_url": { "type": "string" }, "is_password_enabled": { "type": "boolean" }, "unshared_at": { "type": "string" }, "download_count": { "type": "integer" }, "preview_count": { "type": "integer" }, "access": { "type": "string" }, "permissions": { "properties": { "can_download": { "type": "boolean" }, "can_preview": { "type": "boolean" } } } }, "description": "The shared link object for this file.", "type": "object" }, "parent": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" } }, "description": "The folder this file is contained in.", "type": "object" }, "item_status": { "description": "Whether this item is deleted or not.", "type": "string" }, "version_number": { "description": "Whether this folder will be synced by the Box sync clients or not.", "required": false, "type": "string" }, "comment_count": { "description": "The number of comments on a file", "required": false, "type": "integer" } }, "type": "object" } ], "type": "array", "offset": { "type": "integer" }, "limit": { "type": "integer" }, "order": { "ord": { "properties": { "by": { "type": "string" }, "direction": { "type": "string" } }, "type": "object" }, "type": "array", "required": "no" } } } /collaborations: type: base get: description: | Use this to get a list of all the collaborations on a folder i.e. all of the users that have access to that folder. responses: 200: body: example: | { "total_count": 1, "entries": [ { "type": "collaboration", "id": "14176246", "created_by": { "type": "user", "id": "4276790", "name": "David Lee", "login": "david@box.com" }, "created_at": "2011-11-29T12:56:35-08:00", "modified_at": "2012-09-11T15:12:32-07:00", "expires_at": null, "status": "accepted", "accessible_by": { "type": "user", "id": "755492", "name": "Simon Tan", "login": "simon@box.net" }, "role": "editor", "acknowledged_at": "2011-11-29T12:59:40-08:00", "item": null } ] } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "total_count": { "type": "integer" }, "entries": [ { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "created_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "type": "object" }, "created_at": { "type": "timestamp" }, "modified_at": { "type": "timestamp" }, "expires_at": { "type": "timestamp" }, "status": { "type": "string" }, "accessible_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "type": "object" }, "role": { "type": "string" }, "acknowledged_at": { "type": "timestamp" }, "item": { "type": "string" } }, "type": "object" } ], "type": "array" } } /trash/items: type: base get: description: | Retrieves the files and/or folders that have been moved to the trash. Any attribute in the full files or folders objects can be passed in with the fields parameter to get specific attributes, and only those specific attributes back; otherwise, the mini format is returned for each item by default. Multiple attributes can be passed in separated by commas e.g. fields=name,created_at. Paginated results can be retrieved using the limit and offset parameters. queryParameters: fields: description: Attribute(s) to include in the response type: string limit: description: The number of items to return type: integer default: 100 maximum: 1000 offset: description: The item at which to begin the response type: integer default: 0 responses: 200: body: example: | { "total_count": 49542, "entries": [ { "type": "file", "id": "2701979016", "sequence_id": "1", "etag": "1", "sha1": "9d976863fc849f6061ecf9736710bd9c2bce488c", "name": "file Tue Jul 24 145436 2012KWPX5S.csv" }, { "type": "file", "id": "2698211586", "sequence_id": "1", "etag": "1", "sha1": "09b0e2e9760caf7448c702db34ea001f356f1197", "name": "file Tue Jul 24 010055 20129Z6GS3.csv" } ], "offset": 0, "limit": 2 } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "total_count": { "type": "integer" }, "entries": [ { "properties": { "type": { "description": "For files is 'file'", "type": "string" }, "id": { "description": "Box’s unique string identifying this file.", "type": "string" }, "sequence_id": { "description": "A unique ID for use with the /events endpoint.", "type": "string" }, "etag": { "description": "A unique string identifying the version of this file.", "type": "string" }, "sha1": { "description": "The sha1 hash of this file.", "type": "string" }, "name": { "description": "The name of this file.", "type": "string" }, "description": { "description": "The description of this file.", "type": "string" }, "size": { "description": "Size of this file in bytes.", "type": "integer" }, "path_collection": { "paths": { "properties": { "total_count": { "type": "integer" }, "entries": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "description": "Array of entries.", "type": "array" }, "type": "object" }, "description": "The path of folders to this item, starting at the root.", "type": "array" }, "created_at": { "description": "When this file was created on Box’s servers.", "type": "timestamp" }, "modified_at": { "description": "When this file was last updated on the Box servers.", "type": "timestamp" }, "trashed_at": { "description": "When this file was last moved to the trash.", "type": "timestamp" }, "purged_at": { "description": "When this file will be permanently deleted.", "type": "timestamp" }, "content_created_at": { "description": "When the content of this file was created.", "type": "timestamp" }, "content_modified_at": { "description": "When the content of this file was last modified.", "type": "timestamp" }, "created_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who first created file.", "type": "object" }, "modified_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who last updated this file.", "type": "object" }, "owned_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who owns this file.", "type": "object" }, "shared_link": { "properties": { "url": { "type": "string" }, "download_url": { "type": "string" }, "vanity_url": { "type": "string" }, "is_password_enabled": { "type": "boolean" }, "unshared_at": { "type": "string" }, "download_count": { "type": "integer" }, "preview_count": { "type": "integer" }, "access": { "type": "string" }, "permissions": { "properties": { "can_download": { "type": "boolean" }, "can_preview": { "type": "boolean" } } } }, "description": "The shared link object for this file.", "type": "object" }, "parent": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" } }, "description": "The folder this file is contained in.", "type": "object" }, "item_status": { "description": "Whether this item is deleted or not.", "type": "string" }, "version_number": { "description": "Whether this folder will be synced by the Box sync clients or not.", "required": false, "type": "string" }, "comment_count": { "description": "The number of comments on a file", "required": false, "type": "integer" } }, "type": "object" } ], "type": "array", "offset": { "type": "integer" }, "limit": { "type": "integer" }, "order": { "ord": { "properties": { "by": { "type": "string" }, "direction": { "type": "string" } }, "type": "object" }, "type": "array", "required": "no" } } } /files/{fileId}: type: base uriParameters: fileId: description: Box’s unique string identifying this file. type: string get: description: Used to retrieve the metadata about a file. responses: 200: body: example: | { "type": "file", "id": "5000948880", "sequence_id": "3", "etag": "3", "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc", "name": "tigers.jpeg", "description": "a picture of tigers", "size": 629644, "path_collection": { "total_count": 2, "entries": [ { "type": "folder", "id": "0", "sequence_id": null, "etag": null, "name": "All Files" }, { "type": "folder", "id": "11446498", "sequence_id": "1", "etag": "1", "name": "Pictures" } ] }, "created_at": "2012-12-12T10:55:30-08:00", "modified_at": "2012-12-12T11:04:26-08:00", "created_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "modified_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "owned_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "shared_link": { "url": "https://www.box.com/s/rh935iit6ewrmw0unyul", "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg", "vanity_url": null, "is_password_enabled": false, "unshared_at": null, "download_count": 0, "preview_count": 0, "access": "open", "permissions": { "can_download": true, "can_preview": true } }, "parent": { "type": "folder", "id": "11446498", "sequence_id": "1", "etag": "1", "name": "Pictures" }, "item_status": "active" } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "type": { "description": "For files is 'file'", "type": "string" }, "id": { "description": "Box’s unique string identifying this file.", "type": "string" }, "sequence_id": { "description": "A unique ID for use with the /events endpoint.", "type": "string" }, "etag": { "description": "A unique string identifying the version of this file.", "type": "string" }, "sha1": { "description": "The sha1 hash of this file.", "type": "string" }, "name": { "description": "The name of this file.", "type": "string" }, "description": { "description": "The description of this file.", "type": "string" }, "size": { "description": "Size of this file in bytes.", "type": "integer" }, "path_collection": { "paths": { "properties": { "total_count": { "type": "integer" }, "entries": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "description": "Array of entries.", "type": "array" }, "type": "object" }, "description": "The path of folders to this item, starting at the root.", "type": "array" }, "created_at": { "description": "When this file was created on Box’s servers.", "type": "timestamp" }, "modified_at": { "description": "When this file was last updated on the Box servers.", "type": "timestamp" }, "trashed_at": { "description": "When this file was last moved to the trash.", "type": "timestamp" }, "purged_at": { "description": "When this file will be permanently deleted.", "type": "timestamp" }, "content_created_at": { "description": "When the content of this file was created.", "type": "timestamp" }, "content_modified_at": { "description": "When the content of this file was last modified.", "type": "timestamp" }, "created_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who first created file.", "type": "object" }, "modified_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who last updated this file.", "type": "object" }, "owned_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who owns this file.", "type": "object" }, "shared_link": { "properties": { "url": { "type": "string" }, "download_url": { "type": "string" }, "vanity_url": { "type": "string" }, "is_password_enabled": { "type": "boolean" }, "unshared_at": { "type": "string" }, "download_count": { "type": "integer" }, "preview_count": { "type": "integer" }, "access": { "type": "string" }, "permissions": { "properties": { "can_download": { "type": "boolean" }, "can_preview": { "type": "boolean" } } } }, "description": "The shared link object for this file.", "type": "object" }, "parent": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" } }, "description": "The folder this file is contained in.", "type": "object" }, "item_status": { "description": "Whether this item is deleted or not.", "type": "string" }, "version_number": { "description": "Whether this folder will be synced by the Box sync clients or not.", "required": false, "type": "string" }, "comment_count": { "description": "The number of comments on a file", "required": false, "type": "integer" } }, "type": "object" } put: description: | Used to update individual or multiple fields in the file object, including renaming the file, changing it’s description, and creating a shared link for the file. To move a file, change the ID of its parent folder. An optional If-Match header can be included to ensure that client only updates the file if it knows about the latest version. body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "name": { "description": "The new name for the file.", "type": "string" }, "description": { "description": "The new description for the file.", "type": "string" }, "parent": { "description": "The parent folder of this file.", "type": "object" }, "id": { "description": "The ID of the parent folder.", "type": "string" }, "shared_link": { "description": "An object representing this item’s shared link and associated permissions.", "type": "object" }, "access": { "description": "The level of access required for this shared link.", "type": ["open", "company", "collaborators" ] }, "unshared_at": { "description": "The day that this link should be disabled at. Timestamps are rounded off to the given day.", "type": "timestamp" }, "permissions": { "description": "The set of permissions that apply to this link.", "type": "object" }, "permissions.download": { "description": "Whether this link allows downloads.", "type": "boolean" }, "permissions.preview": { "description": "Whether this link allows previews.", "type": "boolean" } } } responses: 200: body: example: | { "type": "file", "id": "5000948880", "sequence_id": "3", "etag": "3", "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc", "name": "new name.jpg", "description": "a picture of tigers", "size": 629644, "path_collection": { "total_count": 2, "entries": [ { "type": "folder", "id": "0", "sequence_id": null, "etag": null, "name": "All Files" }, { "type": "folder", "id": "11446498", "sequence_id": "1", "etag": "1", "name": "Pictures" } ] }, "created_at": "2012-12-12T10:55:30-08:00", "modified_at": "2012-12-12T11:04:26-08:00", "created_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "modified_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "owned_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "shared_link": { "url": "https://www.box.com/s/rh935iit6ewrmw0unyul", "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg", "vanity_url": null, "is_password_enabled": false, "unshared_at": null, "download_count": 0, "preview_count": 0, "access": "open", "permissions": { "can_download": true, "can_preview": true } }, "parent": { "type": "folder", "id": "11446498", "sequence_id": "1", "etag": "1", "name": "Pictures" }, "item_status": "active" } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "type": { "description": "For files is 'file'", "type": "string" }, "id": { "description": "Box’s unique string identifying this file.", "type": "string" }, "sequence_id": { "description": "A unique ID for use with the /events endpoint.", "type": "string" }, "etag": { "description": "A unique string identifying the version of this file.", "type": "string" }, "sha1": { "description": "The sha1 hash of this file.", "type": "string" }, "name": { "description": "The name of this file.", "type": "string" }, "description": { "description": "The description of this file.", "type": "string" }, "size": { "description": "Size of this file in bytes.", "type": "integer" }, "path_collection": { "paths": { "properties": { "total_count": { "type": "integer" }, "entries": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "description": "Array of entries.", "type": "array" }, "type": "object" }, "description": "The path of folders to this item, starting at the root.", "type": "array" }, "created_at": { "description": "When this file was created on Box’s servers.", "type": "timestamp" }, "modified_at": { "description": "When this file was last updated on the Box servers.", "type": "timestamp" }, "trashed_at": { "description": "When this file was last moved to the trash.", "type": "timestamp" }, "purged_at": { "description": "When this file will be permanently deleted.", "type": "timestamp" }, "content_created_at": { "description": "When the content of this file was created.", "type": "timestamp" }, "content_modified_at": { "description": "When the content of this file was last modified.", "type": "timestamp" }, "created_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who first created file.", "type": "object" }, "modified_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who last updated this file.", "type": "object" }, "owned_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who owns this file.", "type": "object" }, "shared_link": { "properties": { "url": { "type": "string" }, "download_url": { "type": "string" }, "vanity_url": { "type": "string" }, "is_password_enabled": { "type": "boolean" }, "unshared_at": { "type": "string" }, "download_count": { "type": "integer" }, "preview_count": { "type": "integer" }, "access": { "type": "string" }, "permissions": { "properties": { "can_download": { "type": "boolean" }, "can_preview": { "type": "boolean" } } } }, "description": "The shared link object for this file.", "type": "object" }, "parent": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" } }, "description": "The folder this file is contained in.", "type": "object" }, "item_status": { "description": "Whether this item is deleted or not.", "type": "string" }, "version_number": { "description": "Whether this folder will be synced by the Box sync clients or not.", "required": false, "type": "string" }, "comment_count": { "description": "The number of comments on a file", "required": false, "type": "integer" } }, "type": "object" } delete: description: | Discards a file to the trash. The 'etag' of the file can be included as an 'If-Match' header to prevent race conditions. Trash: Depending on the enterprise settings for this user, the item will either be actually deleted from Box or moved to the trash. responses: 204: description: Confirm deletion. 412: description: If the 'If-Match' header is sent and fails. post: description: | Restores an item that has been moved to the trash. Default behavior is to restore the item to the folder it was in before it was moved to the trash. If that parent folder no longer exists or if there is now an item with the same name in that parent folder, the new parent folder and/or new name will need to be included in the request. body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "name": { "description": "The new name for this item.", "type": "string" }, "parent": { "description": "The new parent folder for this item.", "type": "object" }, "id": { "description": "The id of the new parent folder.", "type": "string" } } } responses: 201: body: example: | { "type": "file", "id": "5859258256", "sequence_id": "3", "etag": "3", "sha1": "4bd9e98652799fc57cf9423e13629c151152ce6c", "name": "Screenshot_1_30_13_6_37_PM.png", "description": "", "size": 163265, "path_collection": { "total_count": 1, "entries": [ { "type": "folder", "id": "0", "sequence_id": null, "etag": null, "name": "All Files" } ] }, "created_at": "2013-01-30T18:43:56-08:00", "modified_at": "2013-02-07T10:56:58-08:00", "trashed_at": null, "purged_at": null, "content_created_at": "2013-01-30T18:43:56-08:00", "content_modified_at": "2013-02-07T10:56:58-08:00", "created_by": { "type": "user", "id": "181757341", "name": "sean test", "login": "sean+test@box.com" }, "modified_by": { "type": "user", "id": "181757341", "name": "sean test", "login": "sean+test@box.com" }, "owned_by": { "type": "user", "id": "181757341", "name": "sean test", "login": "sean+test@box.com" }, "shared_link": { "url": "https://seanrose.box.com/s/ebgti08mtmhbpb4vlp55", "download_url": "https://seanrose.box.com/shared/static/ebgti08mtmhbpb4vlp55.png", "vanity_url": null, "is_password_enabled": false, "unshared_at": null, "download_count": 0, "preview_count": 4, "access": "open", "permissions": { "can_download": true, "can_preview": true } }, "parent": { "type": "folder", "id": "0", "sequence_id": null, "etag": null, "name": "All Files" }, "item_status": "active" } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "type": { "description": "For files is 'file'", "type": "string" }, "id": { "description": "Box’s unique string identifying this file.", "type": "string" }, "sequence_id": { "description": "A unique ID for use with the /events endpoint.", "type": "string" }, "etag": { "description": "A unique string identifying the version of this file.", "type": "string" }, "sha1": { "description": "The sha1 hash of this file.", "type": "string" }, "name": { "description": "The name of this file.", "type": "string" }, "description": { "description": "The description of this file.", "type": "string" }, "size": { "description": "Size of this file in bytes.", "type": "integer" }, "path_collection": { "paths": { "properties": { "total_count": { "type": "integer" }, "entries": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "description": "Array of entries.", "type": "array" }, "type": "object" }, "description": "The path of folders to this item, starting at the root.", "type": "array" }, "created_at": { "description": "When this file was created on Box’s servers.", "type": "timestamp" }, "modified_at": { "description": "When this file was last updated on the Box servers.", "type": "timestamp" }, "trashed_at": { "description": "When this file was last moved to the trash.", "type": "timestamp" }, "purged_at": { "description": "When this file will be permanently deleted.", "type": "timestamp" }, "content_created_at": { "description": "When the content of this file was created.", "type": "timestamp" }, "content_modified_at": { "description": "When the content of this file was last modified.", "type": "timestamp" }, "created_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who first created file.", "type": "object" }, "modified_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who last updated this file.", "type": "object" }, "owned_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who owns this file.", "type": "object" }, "shared_link": { "properties": { "url": { "type": "string" }, "download_url": { "type": "string" }, "vanity_url": { "type": "string" }, "is_password_enabled": { "type": "boolean" }, "unshared_at": { "type": "string" }, "download_count": { "type": "integer" }, "preview_count": { "type": "integer" }, "access": { "type": "string" }, "permissions": { "properties": { "can_download": { "type": "boolean" }, "can_preview": { "type": "boolean" } } } }, "description": "The shared link object for this file.", "type": "object" }, "parent": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" } }, "description": "The folder this file is contained in.", "type": "object" }, "item_status": { "description": "Whether this item is deleted or not.", "type": "string" }, "version_number": { "description": "Whether this folder will be synced by the Box sync clients or not.", "required": false, "type": "string" }, "comment_count": { "description": "The number of comments on a file", "required": false, "type": "integer" } }, "type": "object" } /content: type: base get: description: | Retrieves the actual data of the file. An optional version parameter can be set to download a previous version of the file. queryParameters: version: description: The ID specific version of this file to download. type: string responses: 302: description: Found 202: description: | If the file is not ready to be downloaded (i.e. in the case where the file was uploaded immediately before the download request), a response with an HTTP status of 202 Accepted will be returned with a 'Retry-After' header indicating the time in seconds after which the file will be available for the client to download. /versions: type: base get: description: | If there are previous versions of this file, this method can be used to retrieve metadata about the older versions. ALERT: Versions are only tracked for Box users with premium accounts. responses: 200: description: | An array of version objects are returned. If there are no previous versions of this file, then an empty array will be returned. body: example: | { "total_count": 1, "entries": [ { "type": "file_version", "id": "672259576", "sha1": "359c6c1ed98081b9a69eb3513b9deced59c957f9", "name": "Dragons.js", "size": 92556, "created_at": "2012-08-20T10:20:30-07:00", "modified_at": "2012-11-28T13:14:58-08:00", "modified_by": { "type": "user", "id": "183732129", "name": "sean rose", "login": "sean+apitest@box.com" } } ] } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "total_count": { "type": "integer" }, "entries": [ { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sha1": { "type": "string" }, "name": { "type": "string" }, "size": { "type": "integer" }, "created_at": { "type": "timestamp" }, "modified_at": { "type": "timestamp" }, "modified_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "type": "object" } }, "type": "object" } ], "type": "array" } } /copy: type: base post: description: | Used to create a copy of a file in another folder. The original version of the file will not be altered. body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "parent": { "description": "Folder object representing the new location of the file.", "type": "string" }, "id": { "description": "The ID of the destination folder.", "type": "string" }, "name": { "description": "An optional new name for the file", "type": "string" } }, "required": [ "parent", "id"] } responses: 200: body: example: | { "type": "file", "id": "5000948880", "sequence_id": "3", "etag": "3", "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc", "name": "tigers.jpeg", "description": "a picture of tigers", "size": 629644, "path_collection": { "total_count": 2, "entries": [ { "type": "folder", "id": "0", "sequence_id": null, "etag": null, "name": "All Files" }, { "type": "folder", "id": "11446498", "sequence_id": "1", "etag": "1", "name": "Pictures" } ] }, "created_at": "2012-12-12T10:55:30-08:00", "modified_at": "2012-12-12T11:04:26-08:00", "created_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "modified_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "owned_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "shared_link": { "url": "https://www.box.com/s/rh935iit6ewrmw0unyul", "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg", "vanity_url": null, "is_password_enabled": false, "unshared_at": null, "download_count": 0, "preview_count": 0, "access": "open", "permissions": { "can_download": true, "can_preview": true } }, "parent": { "type": "folder", "id": "11446498", "sequence_id": "1", "etag": "1", "name": "Pictures" }, "item_status": "active" } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "type": { "description": "For files is 'file'", "type": "string" }, "id": { "description": "Box’s unique string identifying this file.", "type": "string" }, "sequence_id": { "description": "A unique ID for use with the /events endpoint.", "type": "string" }, "etag": { "description": "A unique string identifying the version of this file.", "type": "string" }, "sha1": { "description": "The sha1 hash of this file.", "type": "string" }, "name": { "description": "The name of this file.", "type": "string" }, "description": { "description": "The description of this file.", "type": "string" }, "size": { "description": "Size of this file in bytes.", "type": "integer" }, "path_collection": { "paths": { "properties": { "total_count": { "type": "integer" }, "entries": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "description": "Array of entries.", "type": "array" }, "type": "object" }, "description": "The path of folders to this item, starting at the root.", "type": "array" }, "created_at": { "description": "When this file was created on Box’s servers.", "type": "timestamp" }, "modified_at": { "description": "When this file was last updated on the Box servers.", "type": "timestamp" }, "trashed_at": { "description": "When this file was last moved to the trash.", "type": "timestamp" }, "purged_at": { "description": "When this file will be permanently deleted.", "type": "timestamp" }, "content_created_at": { "description": "When the content of this file was created.", "type": "timestamp" }, "content_modified_at": { "description": "When the content of this file was last modified.", "type": "timestamp" }, "created_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who first created file.", "type": "object" }, "modified_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who last updated this file.", "type": "object" }, "owned_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who owns this file.", "type": "object" }, "shared_link": { "properties": { "url": { "type": "string" }, "download_url": { "type": "string" }, "vanity_url": { "type": "string" }, "is_password_enabled": { "type": "boolean" }, "unshared_at": { "type": "string" }, "download_count": { "type": "integer" }, "preview_count": { "type": "integer" }, "access": { "type": "string" }, "permissions": { "properties": { "can_download": { "type": "boolean" }, "can_preview": { "type": "boolean" } } } }, "description": "The shared link object for this file.", "type": "object" }, "parent": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" } }, "description": "The folder this file is contained in.", "type": "object" }, "item_status": { "description": "Whether this item is deleted or not.", "type": "string" }, "version_number": { "description": "Whether this folder will be synced by the Box sync clients or not.", "required": false, "type": "string" }, "comment_count": { "description": "The number of comments on a file", "required": false, "type": "integer" } }, "type": "object" } 409: description: | Will be returned if the intended destination folder is the same, as this will cause a name collision. /thumbnail.extension: type: base get: description: | Retrieves a thumbnail, or smaller image representation, of this file. Sizes of 32x32, 64x64, 128x128, and 256x256 can be returned. Currently thumbnails are only available in .png format and will only be generated for image file formats. There are three success cases that your application needs to account for: - If the thumbnail isn’t available yet, a 202 Accepted HTTP status will be returned, including a 'Location' header pointing to a placeholder graphic that can be used until the thumbnail is returned. A 'Retry-After' header will also be returned, indicating the time in seconds after which the thumbnail will be available. Your application should only attempt to get the thumbnail again after Retry-After time. - If Box can’t generate a thumbnail for this file type, a 302 Found response will be returned, redirecting to a placeholder graphic in the requested size for this particular file type. - If the thumbnail is available, a 200 OK response will be returned with the contents of the thumbnail in the body. - If Box is unable to generate a thumbnail for this particular file, a 404 'Not Found' response will be returned with a code of preview_cannot_be_generated. If there are any bad parameters sent in, a standard 400 'Bad Request' will be returned. queryParameters: min_height: description: The minimum height of the thumbnail. type: integer min_width: description: The minimum width of the thumbnail. type: integer max_height: description: The maximum height of the thumbnail type: integer max_width: description: The maximum width of the thumbnail type: integer /trash: type: base get: description: | Retrieves an item that has been moved to the trash. The full item will be returned, including information about when the it was moved to the trash. responses: 200: body: example: | { "type": "file", "id": "5859258256", "sequence_id": "2", "etag": "2", "sha1": "4bd9e98652799fc57cf9423e13629c151152ce6c", "name": "Screenshot_1_30_13_6_37_PM.png", "description": "", "size": 163265, "path_collection": { "total_count": 1, "entries": [ { "type": "folder", "id": "1", "sequence_id": null, "etag": null, "name": "Trash" } ] }, "created_at": "2013-01-30T18:43:56-08:00", "modified_at": "2013-01-30T18:44:00-08:00", "trashed_at": "2013-02-07T10:49:34-08:00", "purged_at": "2013-03-09T10:49:34-08:00", "content_created_at": "2013-01-30T18:43:56-08:00", "content_modified_at": "2013-01-30T18:44:00-08:00", "created_by": { "type": "user", "id": "181757341", "name": "sean test", "login": "sean+test@box.com" }, "modified_by": { "type": "user", "id": "181757341", "name": "sean test", "login": "sean+test@box.com" }, "owned_by": { "type": "user", "id": "181757341", "name": "sean test", "login": "sean+test@box.com" }, "shared_link": { "url": null, "download_url": null, "vanity_url": null, "is_password_enabled": false, "unshared_at": null, "download_count": 0, "preview_count": 0, "access": "open", "permissions": { "can_download": true, "can_preview": true } }, "parent": { "type": "folder", "id": "0", "sequence_id": null, "etag": null, "name": "All Files" }, "item_status": "trashed" } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "type": { "description": "For files is 'file'", "type": "string" }, "id": { "description": "Box’s unique string identifying this file.", "type": "string" }, "sequence_id": { "description": "A unique ID for use with the /events endpoint.", "type": "string" }, "etag": { "description": "A unique string identifying the version of this file.", "type": "string" }, "sha1": { "description": "The sha1 hash of this file.", "type": "string" }, "name": { "description": "The name of this file.", "type": "string" }, "description": { "description": "The description of this file.", "type": "string" }, "size": { "description": "Size of this file in bytes.", "type": "integer" }, "path_collection": { "paths": { "properties": { "total_count": { "type": "integer" }, "entries": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "description": "Array of entries.", "type": "array" }, "type": "object" }, "description": "The path of folders to this item, starting at the root.", "type": "array" }, "created_at": { "description": "When this file was created on Box’s servers.", "type": "timestamp" }, "modified_at": { "description": "When this file was last updated on the Box servers.", "type": "timestamp" }, "trashed_at": { "description": "When this file was last moved to the trash.", "type": "timestamp" }, "purged_at": { "description": "When this file will be permanently deleted.", "type": "timestamp" }, "content_created_at": { "description": "When the content of this file was created.", "type": "timestamp" }, "content_modified_at": { "description": "When the content of this file was last modified.", "type": "timestamp" }, "created_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who first created file.", "type": "object" }, "modified_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who last updated this file.", "type": "object" }, "owned_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who owns this file.", "type": "object" }, "shared_link": { "properties": { "url": { "type": "string" }, "download_url": { "type": "string" }, "vanity_url": { "type": "string" }, "is_password_enabled": { "type": "boolean" }, "unshared_at": { "type": "string" }, "download_count": { "type": "integer" }, "preview_count": { "type": "integer" }, "access": { "type": "string" }, "permissions": { "properties": { "can_download": { "type": "boolean" }, "can_preview": { "type": "boolean" } } } }, "description": "The shared link object for this file.", "type": "object" }, "parent": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" } }, "description": "The folder this file is contained in.", "type": "object" }, "item_status": { "description": "Whether this item is deleted or not.", "type": "string" }, "version_number": { "description": "Whether this folder will be synced by the Box sync clients or not.", "required": false, "type": "string" }, "comment_count": { "description": "The number of comments on a file", "required": false, "type": "integer" } }, "type": "object" } delete: description: | Permanently deletes an item that is in the trash. The item will no longer exist in Box. This action cannot be undone. responses: 204: description: Item removed. /comments: type: base get: description: | Retrieves the comments on a particular file, if any exist. A collection of comment objects are returned. If there are no comments on the file, an empty comments array is returned. responses: 200: body: example: | { "total_count": 1, "entries": [ { "type": "comment", "id": "191969", "is_reply_comment": false, "message": "These tigers are cool!", "created_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "created_at": "2012-12-12T11:25:01-08:00", "item": { "id": "5000948880", "type": "file" }, "modified_at": "2012-12-12T11:25:01-08:00" } ] } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "total_count": { "type": "integer" }, "entries": [ { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "is_reply_comment": { "type": "boolean" }, "message": { "type": "string" }, "created_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "type": "object" }, "created_at": { "type": "timestamp" }, "item": { "properties": { "id": { "type": "string" }, "type": { "type": "file" } }, "type": "object" }, "modified_at": { "type": "timestamp" } }, "type": "object" } ], "type": "array" } } /tasks: type: base get: description: | Retrieves all of the tasks for given file. A collection of mini task objects is returned. If there are no tasks, an empty collection will be returned. responses: 200: body: example: | { "total_count": 1, "entries": [ { "type": "task", "id": "1786931", "item": { "type": "file", "id": "7026335894", "sequence_id": "6", "etag": "6", "sha1": "81cc829fb8366fcfc108aa6c5a9bde01a6a10c16", "name": "API - Persist On-Behalf-Of information.docx" }, "due_at": null } ] } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "total_count": { "type": "integer" }, "entries": [ { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "item": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "sha1": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "due_at": { "type": "string" } }, "type": "object" } ], "type": "array" } } /shared_items: type: base get: description: | Used to retrieve the metadata about a shared item when only given a shared link. Because of varying permission levels for shared links, a password may be required to retrieve the shared item. Once the item has been retrieved, you can make API requests against the actual resource '/files/{id}' or '/folders/{id}' as long as the shared link and optional password are in the header. A full file or folder object is returned if the shared link is valid and the user has access to it. An error may be returned if the link is invalid, if a password is required, or if the user does not have access to the file. queryParameters: BoxApi: required: true enum: - 0 - 1 - true - false - t - f type: string shared_link: description: The shared link for this item required: true enum: - 0 - 1 - true - false - t - f type: string shared_link_password: description: The password for this shared link type: string responses: 200: body: example: | { "type": "folder", "id": "11446498", "sequence_id": "1", "etag": "1", "name": "Pictures", "created_at": "2012-12-12T10:53:43-08:00", "modified_at": "2012-12-12T11:15:04-08:00", "description": "Some pictures I took", "size": 629644, "path_collection": { "total_count": 1, "entries": [ { "type": "folder", "id": "0", "sequence_id": null, "etag": null, "name": "All Files" } ] }, "created_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "modified_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "owned_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "shared_link": { "url": "https://www.box.com/s/vspke7y05sb214wjokpk", "download_url": "https://www.box.com/shared/static/vspke7y05sb214wjokpk", "vanity_url": null, "is_password_enabled": false, "unshared_at": null, "download_count": 0, "preview_count": 0, "access": "open", "permissions": { "can_download": true, "can_preview": true } }, "folder_upload_email": { "access": "open", "email": "upload.Picture.k13sdz1@u.box.com" }, "parent": { "type": "folder", "id": "0", "sequence_id": null, "etag": null, "name": "All Files" }, "item_status": "active", "item_collection": { "total_count": 1, "entries": [ { "type": "file", "id": "5000948880", "sequence_id": "3", "etag": "3", "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc", "name": "tigers.jpeg" } ], "offset": 0, "limit": 100 } } /comments: type: base post: description: | Used to add a comment by the user to a specific file or comment (i.e. as a reply comment). body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "item": { "description": "The item that this comment will be placed on.", "type": "object" }, "type": { "description": "The type of the item that this comment will be placed on.", "type": [ "file", "comment" ] }, "id": { "description": "The id of the item that this comment will be placed on.", "type": "string" }, "message": { "description": "The text body of the comment.", "type": "string" } }, "required": [ "item" ] } responses: 200: body: example: | { "type": "comment", "id": "191969", "is_reply_comment": false, "message": "These tigers are cool!", "created_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "created_at": "2012-12-12T11:25:01-08:00", "item": { "id": "5000948880", "type": "file" }, "modified_at": "2012-12-12T11:25:01-08:00" } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "type": { "description": "For comments is 'comment'.", "type": "string" }, "id": { "description": "A unique string identifying this comment.", "type": "string" }, "is_reply_comment": { "description": "Whether or not this comment is a reply to another comment.", "type": "boolean" }, "message": { "description": "The comment text that the user typed.", "type": "string" }, "tagged_message": { "description": "The string representing the comment text with @mentions included.", "required": false, "type": "string" }, "created_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "A mini user object representing the author of the comment.", "type": "object" }, "dcreated_at": { "description": "The time this comment was created.", "type": "timestamp" }, "item": { "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "description": "The object this comment was placed on.", "type": "object" }, "modified_at": { "description": "The time this comment was last modified.", "type": "timestamp" } }, "required": false, "type": "object" } /{commentId}: type: base uriParameters: commentId: description: Box’s unique string identifying this comment. put: description: | Used to update the message of the comment. The full updated comment object is returned if the ID is valid and if the user has access to the comment. body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "message": { "description": "The desired text for the comment message.", "type": "string" } }, "required": [ "message" ] } responses: 200: body: example: | { "type": "comment", "id": "191969", "is_reply_comment": false, "message": "These tigers are cool!", "created_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "created_at": "2012-12-12T11:25:01-08:00", "item": { "id": "5000948880", "type": "file" }, "modified_at": "2012-12-12T11:25:01-08:00" } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "type": { "description": "For comments is 'comment'.", "type": "string" }, "id": { "description": "A unique string identifying this comment.", "type": "string" }, "is_reply_comment": { "description": "Whether or not this comment is a reply to another comment.", "type": "boolean" }, "message": { "description": "The comment text that the user typed.", "type": "string" }, "tagged_message": { "description": "The string representing the comment text with @mentions included.", "required": false, "type": "string" }, "created_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "A mini user object representing the author of the comment.", "type": "object" }, "dcreated_at": { "description": "The time this comment was created.", "type": "timestamp" }, "item": { "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "description": "The object this comment was placed on.", "type": "object" }, "modified_at": { "description": "The time this comment was last modified.", "type": "timestamp" } }, "required": false, "type": "object" } get: description: | Used to retrieve the message and metadata about a specific comment. Information about the user who created the comment is also included. responses: 200: body: example: | { "type": "comment", "id": "191969", "is_reply_comment": false, "message": "These tigers are cool!", "created_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "created_at": "2012-12-12T11:25:01-08:00", "item": { "id": "5000948880", "type": "file" }, "modified_at": "2012-12-12T11:25:01-08:00" } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "type": { "description": "For comments is 'comment'.", "type": "string" }, "id": { "description": "A unique string identifying this comment.", "type": "string" }, "is_reply_comment": { "description": "Whether or not this comment is a reply to another comment.", "type": "boolean" }, "message": { "description": "The comment text that the user typed.", "type": "string" }, "tagged_message": { "description": "The string representing the comment text with @mentions included.", "required": false, "type": "string" }, "created_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "A mini user object representing the author of the comment.", "type": "object" }, "dcreated_at": { "description": "The time this comment was created.", "type": "timestamp" }, "item": { "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "description": "The object this comment was placed on.", "type": "object" }, "modified_at": { "description": "The time this comment was last modified.", "type": "timestamp" } }, "required": false, "type": "object" } delete: description: | Permanently deletes a comment. An empty 200 response is returned to confirm deletion of the comment. Errors can be thrown if the ID is invalid or if the user is not authorized to delete this particular comment. responses: 200: description: Confirm deletion of the comment. /collaborations: type: base post: description: | Used to add a collaboration for a single user to a folder. Either an email address or a user ID can be used to create the collaboration. body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "item": { "description": "The item to add the collaboration on.", "type": "object" }, "id": { "description": "The ID of the item to add the collaboration on.", "type": "string" }, "type": { "description": "Must be 'folder'.", "type": "string" }, "accessible_by": { "description": "The user who this collaboration applies to.", "type": "object" }, "role": { "description": "The access level of this collaboration.", "type": ["editor", "viewer", "previewer", "uploader", "previewer uploader", "viewer uploader", "co-owner" ] }, "id": { "description": "The ID of this user.", "type": "string" }, "login": { "description": "An email address (does not need to be a Box user).", "type": "string" } }, "required": [ "description", "id", "type", "accessible_by", "role" ] } responses: 200: body: example: | { "type": "collaboration", "id": "791293", "created_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "created_at": "2012-12-12T10:54:37-08:00", "modified_at": "2012-12-12T11:30:43-08:00", "expires_at": null, "status": "accepted", "accessible_by": { "type": "user", "id": "18203124", "name": "sean", "login": "sean+test@box.com" }, "role": "editor", "acknowledged_at": "2012-12-12T11:30:43-08:00", "item": { "type": "folder", "id": "11446500", "sequence_id": "0", "etag": "0", "name": "Shared Pictures" } } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "type": { "description": "For collaborations is 'collaboration'", "type": "string" }, "id": { "description": "A unique string identifying this collaboration.", "type": "string" }, "created_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who created this collaboration.", "type": "object" }, "created_at": { "description": "The time this collaboration was created.", "type": "timestamp" }, "modified_at": { "description": "The time this collaboration was last modified.", "type": "timestamp" }, "expires_at": { "description": "The time this collaboration will expire.", "type": "timestamp" }, "status": { "description": "The status of this collab.", "enum": [ "accepted", "pending", "rejected" ] }, "accecible_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who the collaboration applies to.", "type": "object" }, "role": { "description": "The level of access this user has.", "enum": [ "editor", "viewer", "previewer", "uploader", "previewer uploader", "viewer uploader", "co-owner" ] }, "acknowledged_at": { "description": "When the 'status' of this collab was changed.", "type": "timestamp" }, "item": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" } }, "description": "The folder this collaboration is related to", "type": "object" } } } /{collabId}: type: base uriParameters: collabId: description: Box’s unique string identifying this collaboration. type: string put: description: | Used to edit an existing collaboration. The updated collaboration object is returned. Errors may occur if the IDs are invalid or if the user does not have permissions to edit the collaboration. body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "role": { "description": "The access level of this collaboration", "enum": ["editor", "viewer", "previewer", "uploader", "previewer uploader", "viewer uploader", "co-owner" ] }, "status": { "description": "Whether this collaboration has been accepted.", "enum": ["accepted", "pending", "rejected" ] } } } responses: 200: body: example: | { "type": "collaboration", "id": "791293", "created_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "created_at": "2012-12-12T10:54:37-08:00", "modified_at": "2012-12-12T11:30:43-08:00", "expires_at": null, "status": "accepted", "accessible_by": { "type": "user", "id": "18203124", "name": "sean", "login": "sean+test@box.com" }, "role": "viewer", "acknowledged_at": "2012-12-12T11:30:43-08:00", "item": { "type": "folder", "id": "11446500", "sequence_id": "0", "etag": "0", "name": "Shared Pictures" } } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "type": { "description": "For collaborations is 'collaboration'", "type": "string" }, "id": { "description": "A unique string identifying this collaboration.", "type": "string" }, "created_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who created this collaboration.", "type": "object" }, "created_at": { "description": "The time this collaboration was created.", "type": "timestamp" }, "modified_at": { "description": "The time this collaboration was last modified.", "type": "timestamp" }, "expires_at": { "description": "The time this collaboration will expire.", "type": "timestamp" }, "status": { "description": "The status of this collab.", "enum": [ "accepted", "pending", "rejected" ] }, "accecible_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who the collaboration applies to.", "type": "object" }, "role": { "description": "The level of access this user has.", "enum": [ "editor", "viewer", "previewer", "uploader", "previewer uploader", "viewer uploader", "co-owner" ] }, "acknowledged_at": { "description": "When the 'status' of this collab was changed.", "type": "timestamp" }, "item": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" } }, "description": "The folder this collaboration is related to", "type": "object" } } } delete: description: | Used to delete a single collaboration. A blank 200 response is returned if the ID is valid, and the user has permissions to remove the collaboration. responses: 200: description: User removed. get: description: | Used to get information about a single collaboration. All collaborations for a single folder can be retrieved through 'GET /folders/{id}/collaborations'. The collaboration object is returned. Errors may occur if the IDs are invalid or if the user does not have permissions to see the collaboration. queryParameters: status: description: Can only be 'pending'. enum: [ "pending" ] responses: 200: body: example: | { "type": "collaboration", "id": "791293", "created_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "created_at": "2012-12-12T10:54:37-08:00", "modified_at": "2012-12-12T11:30:43-08:00", "expires_at": null, "status": "accepted", "accessible_by": { "type": "user", "id": "18203124", "name": "sean", "login": "sean+test@box.com" }, "role": "editor", "acknowledged_at": "2012-12-12T11:30:43-08:00", "item": { "type": "folder", "id": "11446500", "sequence_id": "0", "etag": "0", "name": "Shared Pictures" } } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "type": { "description": "For collaborations is 'collaboration'", "type": "string" }, "id": { "description": "A unique string identifying this collaboration.", "type": "string" }, "created_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who created this collaboration.", "type": "object" }, "created_at": { "description": "The time this collaboration was created.", "type": "timestamp" }, "modified_at": { "description": "The time this collaboration was last modified.", "type": "timestamp" }, "expires_at": { "description": "The time this collaboration will expire.", "type": "timestamp" }, "status": { "description": "The status of this collab.", "enum": [ "accepted", "pending", "rejected" ] }, "accecible_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who the collaboration applies to.", "type": "object" }, "role": { "description": "The level of access this user has.", "enum": [ "editor", "viewer", "previewer", "uploader", "previewer uploader", "viewer uploader", "co-owner" ] }, "acknowledged_at": { "description": "When the 'status' of this collab was changed.", "type": "timestamp" }, "item": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" } }, "description": "The folder this collaboration is related to", "type": "object" } } } /search: type: base get: description: | Searching a User’s Account. The search endpoint provides a simple way of finding items that are accessible in a given user’s Box account. A collection of search results is returned. If there are no matching search results, the entries array will be empty. queryParameters: query: description: | The string to search for; can be matched against item names, descriptions, text content of a file, and other fields of the different item types. required: true enum: - 0 - 1 - true - false - t - f type: string limit: description: Number of search results to return type: integer default: 30 maximum: 200 offset: description: The search result at which to start the response. type: integer default: 0 responses: 200: body: example: | { "total_count": 4, "entries": [ { "type": "file", "id": "1874102965", "sequence_id": "0", "etag": "0", "sha1": "63a112a4567fb556f5269735102a2f24f2cbea56", "name": "football.jpg", "description": "", "size": 260271, "path_collection": { "total_count": 1, "entries": [ { "type": "folder", "id": "0", "sequence_id": null, "etag": null, "name": "All Files" } ] }, "created_at": "2012-03-22T18:25:07-07:00", "modified_at": "2012-10-25T14:40:05-07:00", "created_by": { "type": "user", "id": "175065494", "name": "Andrew Luck", "login": "aluck@colts.com" }, "modified_by": { "type": "user", "id": "175065494", "name": "Andrew Luck", "login": "aluck@colts.com" }, "owned_by": { "type": "user", "id": "175065494", "name": "Andrew Luck", "login": "aluck@colts.com" }, "shared_link": null, "parent": { "type": "folder", "id": "0", "sequence_id": null, "etag": null, "name": "All Files" }, "item_status": "active" } ], "offset": 0, "limit": 1 } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "total_count": { "type": "integer" }, "entries": [ { "properties": { "type": { "description": "For files is 'file'", "type": "string" }, "id": { "description": "Box’s unique string identifying this file.", "type": "string" }, "sequence_id": { "description": "A unique ID for use with the /events endpoint.", "type": "string" }, "etag": { "description": "A unique string identifying the version of this file.", "type": "string" }, "sha1": { "description": "The sha1 hash of this file.", "type": "string" }, "name": { "description": "The name of this file.", "type": "string" }, "description": { "description": "The description of this file.", "type": "string" }, "size": { "description": "Size of this file in bytes.", "type": "integer" }, "path_collection": { "paths": { "properties": { "total_count": { "type": "integer" }, "entries": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "description": "Array of entries.", "type": "array" }, "type": "object" }, "description": "The path of folders to this item, starting at the root.", "type": "array" }, "created_at": { "description": "When this file was created on Box’s servers.", "type": "timestamp" }, "modified_at": { "description": "When this file was last updated on the Box servers.", "type": "timestamp" }, "trashed_at": { "description": "When this file was last moved to the trash.", "type": "timestamp" }, "purged_at": { "description": "When this file will be permanently deleted.", "type": "timestamp" }, "content_created_at": { "description": "When the content of this file was created.", "type": "timestamp" }, "content_modified_at": { "description": "When the content of this file was last modified.", "type": "timestamp" }, "created_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who first created file.", "type": "object" }, "modified_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who last updated this file.", "type": "object" }, "owned_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who owns this file.", "type": "object" }, "shared_link": { "properties": { "url": { "type": "string" }, "download_url": { "type": "string" }, "vanity_url": { "type": "string" }, "is_password_enabled": { "type": "boolean" }, "unshared_at": { "type": "string" }, "download_count": { "type": "integer" }, "preview_count": { "type": "integer" }, "access": { "type": "string" }, "permissions": { "properties": { "can_download": { "type": "boolean" }, "can_preview": { "type": "boolean" } } } }, "description": "The shared link object for this file.", "type": "object" }, "parent": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" } }, "description": "The folder this file is contained in.", "type": "object" }, "item_status": { "description": "Whether this item is deleted or not.", "type": "string" }, "version_number": { "description": "Whether this folder will be synced by the Box sync clients or not.", "required": false, "type": "string" }, "comment_count": { "description": "The number of comments on a file", "required": false, "type": "integer" } }, "type": "object" } ], "type": "array" } } /events: type: base get: description: | Use this to get events for a given user. A chunk of event objects is returned for the user based on the parameters passed in. Parameters indicating how many chunks are left as well as the next stream_position are also returned. queryParameters: stream_position: description: | The location in the event stream at which you want to start receiving events. Can specify special case `now` to get 0 events and the latest stream position for initialization. A collection of events is returned. type: string default: 0 stream_type: description: Limits the type of events returned enum: [ "all", "chages", "sync" ] default: all limit: description: Limits the number of events returned type: integer default: 100 responses: 200: body: example: | { "chunk_size": 1, "next_stream_position": 1348790499819, "entries": [ { "type": "event", "event_id": "f82c3ba03e41f7e8a7608363cc6c0390183c3f83", "created_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "created_at": "2012-12-12T10:53:43-08:00", "recorded_at": "2012-12-12T10:53:48-08:00", "event_type": "ITEM_CREATE", "session_id": "70090280850c8d2a1933c1", "source": { "type": "folder", "id": "11446498", "sequence_id": "0", "etag": "0", "name": "Pictures", "created_at": "2012-12-12T10:53:43-08:00", "modified_at": "2012-12-12T10:53:43-08:00", "description": null, "size": 0, "created_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "modified_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "owned_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "shared_link": null, "parent": { "type": "folder", "id": "0", "sequence_id": null, "etag": null, "name": "All Files" }, "item_status": "active", "synced": false } } ] } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "chunk_size": { "type": "integer" }, "next_stream_position": { "type": "integer" }, "entries": [ { "properties": { "type": { "type": "string" }, "event_id": { "type": "string" }, "created_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "type": "object" }, "created_at": { "type": "timestamp" }, "recorded_at": { "type": "timestamp" }, "event_type": { "enum": [ "ITEM_CREATE", "ITEM_UPLOAD", "COMMENT_CREATE", "ITEM_DOWNLOAD", "ITEM_PREVIEW", "ITEM_MOVE", "ITEM_COPY", "TASK_ASSIGNMENT_CREATE", "LOCK_CREATE", "LOCK_DESTROY", "ITEM_TRASH", "ITEM_UNDELETE_VIA_TRASH", "COLLAB_ADD_COLLABORATOR", "COLLAB_INVITE_COLLABORATOR", "ITEM_SYNC", "ITEM_UNSYNC", "ITEM_RENAME", "ITEM_SHARED_CREATE", "ITEM_SHARED_UNSHARE", "ITEM_SHARED", "TAG_ITEM_CREATE", "ADD_LOGIN_ACTIVITY_DEVICE", "REMOVE_LOGIN_ACTIVITY_DEVICE", "CHANGE_ADMIN_ROLE" ] }, "session_id": { "type": "string" }, "source": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" }, "created_at": { "type": "timestamp" }, "modified_at": { "type": "timestamp" }, "description": { "type": "string" }, "size": { "type": "integer" }, "created_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "type": "object" }, "modified_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "type": "object" }, "owned_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "type": "object" }, "shared_link": { "type": "string" }, "parent": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "item_status": { "type": "string" }, "synced": { "type": "boolean" } }, "type": "object" } }, "type": "object" } ], "type": "array" } } options: description: | Long polling. To get real-time notification of activity in a Box account, use the long poll feature of the /events API. To do so, first call the /events API with an OPTIONS call to retrieve the long poll URL to use. Next, make a GET request to the provided URL to begin listening for events. If an event occurs within an account you are monitoring, you will receive a response with the value new_change. It's important to note that this response will not come with any other details, but should serve as a prompt to take further action such as calling the /events endpoint with your last known stream_position. After sending this response, the server will close the connection and you will need to repeat the long poll process to begin listening for events again. If no events occur for a period of time after you make the GET request to the long poll URL, you will receive a response with the value reconnect. When you receive this response, you'll make another OPTIONS call to the /events endpoint and repeat the long poll process. responses: 200: body: example: | { "chunk_size":1, "entries":[ { "type":"realtime_server", "url":"http:\/\/2.realtime.services.box.net\/subscribe?channel=cc807c9c4869ffb1c81a&stream_type=all", "ttl":"10", "max_retries":"10", "retry_timeout":610 } ] } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "chunk_size": { "type": "integer" }, "entries": [ { "properties": { "type": { "type": "string" }, "url": { "type": "string" }, "ttl": { "type": "string" }, "max_retries": { "type": "string" }, "retry_timeout": { "type": "integer" } }, "type": "object" } ], "type": "array" } } /users: type: base get: description: | Get All Users in an Enterprise. Returns a list of all users for the Enterprise along with their user_id, public_name, and login. queryParameters: filter_term: description: | A string used to filter the results to only users starting with the filter_term in either the name or the login type: string limit: description: The number of records to return. type: integer default: 100 maximum: 1000 offset: description: The record at which to start type: integer default: 0 responses: 200: body: example: | { "total_count": 1, "entries": [ { "type": "user", "id": "181216415", "name": "sean rose", "login": "sean+awesome@box.com", "created_at": "2012-05-03T21:39:11-07:00", "modified_at": "2012-08-23T14:57:48-07:00", "role": "user", "language": "en", "space_amount": 5368709120, "space_used": 52947, "max_upload_size": 104857600, "tracking_codes": [], "see_managed_users": false, "sync_enabled": true, "status": "active", "job_title": "", "phone": "5555551374", "address": "10 Cloud Way Los Altos CA", "avatar_url": "https://api.box.com/api/avatar/large/181216415" } ] } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "total_count": { "type": "integer" }, "entries": [ { "properties": { "type": { "description": "For users is 'user'.", "type": "string" }, "id": { "description": "A unique string identifying this user.", "type": "string" }, "name": { "description": "The name of this user.", "type": "string" }, "login": { "description": "The email address this user uses to login.", "type": "string" }, "created_at": { "description": "The time this user was created.", "type": "timestamp" }, "modified_at": { "description": "The time this user was last modified.", "type": "timestamp" }, "role": { "description": "This user’s enterprise role.", "enum": [ "admin", "coadmin", "user" ] }, "language": { "description": "The language of this user. ISO 639-1 Language Code.", "type": "string" }, "space_amount": { "description": "The user’s total available space amount in bytes.", "type": "integer" }, "space_used": { "description": "The amount of space in use by the user.", "type": "integer" }, "max_upload_size": { "description": "The maximum individual file size in bytes this user can have.", "type": "integer" }, "tracking_codes": { "description": "An array of key/value pairs set by the user’s admin.", "type": "array" }, "can_see_managed_users": { "description": "Whether this user can see other enterprise users in its contact list.", "type": "boolean" }, "is_sync_enabled": { "description": "Whether or not this user can use Box Sync", "type": "boolean" }, "status": { "description": "Can be active or inactive.", "enum": [ "active", "inactive" ] }, "job_title": { "description": "The user’s job title.", "type": "string" }, "phone": { "description": "The user’s phone number.", "type": "string" }, "address": { "description": "The user’s address.", "type": "string" }, "avatar_url": { "description": "URL of this user’s avatar image.", "type": "string" }, "is_exempt_from_device_limits": { "description": "Whether to exempt this user from Enterprise device limits.", "type": "boolean" }, "is_exempt_from_login_verification": { "description": "Whether or not this user must use two-factor authentication.", "type": "boolean" }, "enterprise": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" } }, "description": "Mini representation of this user’s enterprise, including the ID of its enterprise", "type": "object" } }, "type": "object" } ], "type": "array" } } post: description: | Used to provision a new user in an enterprise. This method only works for enterprise admins. body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "login": { "description": "The email address this user uses to login.", "type": "string" }, "name": { "description": "The name of this user.", "type": "string" }, "role": { "description": "This user’s enterprise role.", "type": [ "coadmin", "user" ] }, "language": { "description": "The language of this user. ISO 639-1 Language Code.", "type": "string", "maxLength": 2 }, "is_sync_enabled": { "description": "Whether or not this user can use Box Sync.", "type": "boolean" }, "job_title": { "properties": "The user’s job title.", "type": "string" }, "phone": { "description": "The user’s phone number.", "type": "string" }, "address": { "description": "The user’s address.", "type": "string" }, "space_amount": { "description": "The user’s total available space amount in bytes.", "type": "number" }, "tracking_codes": { "description": "An array of key/value pairs set by the user’s admin.", "type": "array" }, "can_see_managed_users": { "description": "Whether this user can see other enterprise users in its contact list.", "type": "boolean" }, "status": { "description": "Can be 'active' or 'inactive'", "type": [ "active", "inactive" ] }, "is_exempt_from_device_limits": { "description": "Whether to exempt this user from Enterprise device limits.", "type": "boolean" }, "is_exempt_from_login_verification": { "description": "Whether or not this user must use two-factor authentication.", "type": "boolean" } }, "required": [ "login", "name" ] } responses: 201: body: example: | { "type": "user", "id": "187273718", "name": "Ned Stark", "login": "eddard@box.com", "created_at": "2012-11-15T16:34:28-08:00", "modified_at": "2012-11-15T16:34:29-08:00", "role": "user", "language": "en", "space_amount": 5368709120, "space_used": 0, "max_upload_size": 2147483648, "tracking_codes": [], "can_see_managed_users": true, "is_sync_enabled": true, "status": "active", "job_title": "", "phone": "555-555-5555", "address": "555 Box Lane", "avatar_url": "https://www.box.com/api/avatar/large/187273718", "is_exempt_from_device_limits": false, "is_exempt_from_login_verification": false } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "type": { "description": "For users is 'user'.", "type": "string" }, "id": { "description": "A unique string identifying this user.", "type": "string" }, "name": { "description": "The name of this user.", "type": "string" }, "login": { "description": "The email address this user uses to login.", "type": "string" }, "created_at": { "description": "The time this user was created.", "type": "timestamp" }, "modified_at": { "description": "The time this user was last modified.", "type": "timestamp" }, "role": { "description": "This user’s enterprise role.", "enum": [ "admin", "coadmin", "user" ] }, "language": { "description": "The language of this user. ISO 639-1 Language Code.", "type": "string" }, "space_amount": { "description": "The user’s total available space amount in bytes.", "type": "integer" }, "space_used": { "description": "The amount of space in use by the user.", "type": "integer" }, "max_upload_size": { "description": "The maximum individual file size in bytes this user can have.", "type": "integer" }, "tracking_codes": { "description": "An array of key/value pairs set by the user’s admin.", "type": "array" }, "can_see_managed_users": { "description": "Whether this user can see other enterprise users in its contact list.", "type": "boolean" }, "is_sync_enabled": { "description": "Whether or not this user can use Box Sync", "type": "boolean" }, "status": { "description": "Can be active or inactive.", "enum": [ "actibe", "inactive" ] }, "job_title": { "description": "The user’s job title.", "type": "string" }, "phone": { "description": "The user’s phone number.", "type": "string" }, "address": { "description": "The user’s address.", "type": "string" }, "avatar_url": { "description": "URL of this user’s avatar image.", "type": "string" }, "is_exempt_from_device_limits": { "description": "Whether to exempt this user from Enterprise device limits.", "type": "boolean" }, "is_exempt_from_login_verification": { "description": "Whether or not this user must use two-factor authentication.", "type": "boolean" }, "enterprise": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" } }, "description": "Mini representation of this user’s enterprise, including the ID of its enterprise", "type": "object" } } } /me: type: base get: description: | Get the Current User’s Information. Retrieves information about the user who is currently logged in i.e. the user for whom this auth token was generated. Returns a single complete user object. An error is returned if a valid auth token is not included in the API request. responses: 200: body: example: | { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com", "created_at": "2012-03-26T15:43:07-07:00", "modified_at": "2012-12-12T11:34:29-08:00", "language": "en", "space_amount": 5368709120, "space_used": 2377016, "max_upload_size": 262144000, "status": "active", "job_title": "Employee", "phone": "5555555555", "address": "555 Office Drive", "avatar_url": "https://www.box.com/api/avatar/large/17738362" } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "type": { "description": "For users is 'user'.", "type": "string" }, "id": { "description": "A unique string identifying this user.", "type": "string" }, "name": { "description": "The name of this user.", "type": "string" }, "login": { "description": "The email address this user uses to login.", "type": "string" }, "created_at": { "description": "The time this user was created.", "type": "timestamp" }, "modified_at": { "description": "The time this user was last modified.", "type": "timestamp" }, "role": { "description": "This user’s enterprise role.", "enum": [ "admin", "coadmin", "user" ] }, "language": { "description": "The language of this user. ISO 639-1 Language Code.", "type": "string" }, "space_amount": { "description": "The user’s total available space amount in bytes.", "type": "integer" }, "space_used": { "description": "The amount of space in use by the user.", "type": "integer" }, "max_upload_size": { "description": "The maximum individual file size in bytes this user can have.", "type": "integer" }, "tracking_codes": { "description": "An array of key/value pairs set by the user’s admin.", "type": "array" }, "can_see_managed_users": { "description": "Whether this user can see other enterprise users in its contact list.", "type": "boolean" }, "is_sync_enabled": { "description": "Whether or not this user can use Box Sync", "type": "boolean" }, "status": { "description": "Can be active or inactive.", "enum": [ "actibe", "inactive" ] }, "job_title": { "description": "The user’s job title.", "type": "string" }, "phone": { "description": "The user’s phone number.", "type": "string" }, "address": { "description": "The user’s address.", "type": "string" }, "avatar_url": { "description": "URL of this user’s avatar image.", "type": "string" }, "is_exempt_from_device_limits": { "description": "Whether to exempt this user from Enterprise device limits.", "type": "boolean" }, "is_exempt_from_login_verification": { "description": "Whether or not this user must use two-factor authentication.", "type": "boolean" }, "enterprise": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" } }, "description": "Mini representation of this user’s enterprise, including the ID of its enterprise", "type": "object" } } } /{userId}: type: base uriParameters: userId: description: Box’s unique string identifying this user. type: string put: description: | Update a User’s Information. Used to edit the settings and information about a user. This method only works for enterprise admins. To roll a user out of the enterprise (and convert them to a standalone free user), update the special 'enterprise' attribute to be 'null'. Returns the a full user object for the updated user. Errors may be thrown when the fields are invalid or this API call is made from a non-admin account. queryParameters: notify: description: | Whether the user should receive an email when they are rolled out of an enterprise type: string body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "enterprise": { "description": "Setting this to 'null' will roll the user out of the enterprise and make them a free user.", "type": "string" }, "name": { "description": "The name of this user.", "type": "string" }, "role": { "description": "This user’s enterprise role. Can be 'coadmin' or 'user'.", "type": [ "coadmin", "user" ] }, "language": { "description": "The language of this user. ISO 639-1 Language Code.", "type": "string", "maxLength": 2 }, "is_sync_enabled": { "description": "Whether or not this user can use Box Sync.", "type": "boolean" }, "job_title": { "description": "The user’s job title.", "type": "string" }, "phone": { "description": "The user’s phone number.", "type": "string" }, "address": { "description": "The user’s address.", "type": "string" }, "space_amount": { "description": "The user’s total available space amount in byte. A value of '-1' grants unlimited storage.", "type": "number" }, "tracking_codes": { "description": "An array of key/value pairs set by the user’s admin.", "type": "array" }, "can_see_managed_users": { "description": "Whether this user can see other enterprise users in its contact list.", "type": "boolean" }, "status": { "description": "Can be 'active' or 'inactive'.", "type": [ "active", "inactive" ] }, "is_exempt_from_device_limits": { "description": "Whether to exempt this user from Enterprise device limits.", "type": "boolean" }, "is_exempt_from_login_verification": { "description": "Whether or not this user must use two-factor authentication.", "type": "boolean" }, "is_password_reset_required": { "description": "Whether or not the user is required to reset password.", "type": "boolean" } } } responses: 200: body: example: | { "type": "user", "id": "181216415", "name": "sean", "login": "sean+awesome@box.com", "created_at": "2012-05-03T21:39:11-07:00", "modified_at": "2012-12-06T18:17:16-08:00", "role": "admin", "language": "en", "space_amount": 5368709120, "space_used": 1237179286, "max_upload_size": 2147483648, "tracking_codes": [], "can_see_managed_users": true, "is_sync_enabled": true, "status": "active", "job_title": "", "phone": "6509241374", "address": "", "avatar_url": "https://www.box.com/api/avatar/large/181216415", "is_exempt_from_device_limits": false, "is_exempt_from_login_verification": false } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "type": { "description": "For users is 'user'.", "type": "string" }, "id": { "description": "A unique string identifying this user.", "type": "string" }, "name": { "description": "The name of this user.", "type": "string" }, "login": { "description": "The email address this user uses to login.", "type": "string" }, "created_at": { "description": "The time this user was created.", "type": "timestamp" }, "modified_at": { "description": "The time this user was last modified.", "type": "timestamp" }, "role": { "description": "This user’s enterprise role.", "enum": [ "admin", "coadmin", "user" ] }, "language": { "description": "The language of this user. ISO 639-1 Language Code.", "type": "string" }, "space_amount": { "description": "The user’s total available space amount in bytes.", "type": "integer" }, "space_used": { "description": "The amount of space in use by the user.", "type": "integer" }, "max_upload_size": { "description": "The maximum individual file size in bytes this user can have.", "type": "integer" }, "tracking_codes": { "description": "An array of key/value pairs set by the user’s admin.", "type": "array" }, "can_see_managed_users": { "description": "Whether this user can see other enterprise users in its contact list.", "type": "boolean" }, "is_sync_enabled": { "description": "Whether or not this user can use Box Sync", "type": "boolean" }, "status": { "description": "Can be active or inactive.", "enum": [ "actibe", "inactive" ] }, "job_title": { "description": "The user’s job title.", "type": "string" }, "phone": { "description": "The user’s phone number.", "type": "string" }, "address": { "description": "The user’s address.", "type": "string" }, "avatar_url": { "description": "URL of this user’s avatar image.", "type": "string" }, "is_exempt_from_device_limits": { "description": "Whether to exempt this user from Enterprise device limits.", "type": "boolean" }, "is_exempt_from_login_verification": { "description": "Whether or not this user must use two-factor authentication.", "type": "boolean" }, "enterprise": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" } }, "description": "Mini representation of this user’s enterprise, including the ID of its enterprise", "type": "object" } } } delete: description: | Deletes a user in an enterprise account. An empty 200 response is sent to confirm deletion of the user. If the user still has files in their account and the ???force’ parameter is not sent, an error is returned. queryParameters: notify: description: | Determines if the destination user should receive email notification of the transfer. type: string force: description: | Whether or not the user should be deleted even if this user still own files. type: string responses: 200: description: Confirm deletion of the user. /folders/{folderId}: type: base uriParameters: folderId: type: string put: description: | Move Folder into Another User’s Folder. Moves all of the content from within one user’s folder into a new folder in another user’s account. You can move folders across users as long as the you have administrative permissions. To move everything from the root folder, use "0" which always represents the root folder of a Box account. Returns the information for the newly created destination folder. An error is thrown if you do not have the necessary permissions to move the folder. Alert: folder_id: Currently only moving of the root folder (0) is supported. queryParameters: notify: description: | Determines if the destination user should receive email notification of the transfer. type: string body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "owned_by": { "description": "The user who the folder will be transferred to.", "type": "string" }, "id": { "description": "The ID of the user who the folder will be transferred to.", "type": "string" } }, "required": [ "owned_by", "id" ] } responses: 200: body: example: | { "type": "folder", "id": "11446498", "sequence_id": "1", "etag": "1", "name": "Pictures", "created_at": "2012-12-12T10:53:43-08:00", "modified_at": "2012-12-12T11:15:04-08:00", "description": "Some pictures I took", "size": 629644, "path_collection": { "total_count": 1, "entries": [ { "type": "folder", "id": "0", "sequence_id": null, "etag": null, "name": "All Files" } ] }, "created_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "modified_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "owned_by": { "type": "user", "id": "17738362", "name": "sean rose", "login": "sean@box.com" }, "shared_link": { "url": "https://www.box.com/s/vspke7y05sb214wjokpk", "download_url": "https://www.box.com/shared/static/vspke7y05sb214wjokpk", "vanity_url": null, "is_password_enabled": false, "unshared_at": null, "download_count": 0, "preview_count": 0, "access": "open", "permissions": { "can_download": true, "can_preview": true } }, "folder_upload_email": { "access": "open", "email": "upload.Picture.k13sdz1@u.box.com" }, "parent": { "type": "folder", "id": "0", "sequence_id": null, "etag": null, "name": "All Files" }, "item_status": "active", "item_collection": { "total_count": 1, "entries": [ { "type": "file", "id": "5000948880", "sequence_id": "3", "etag": "3", "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc", "name": "tigers.jpeg" } ], "offset": 0, "limit": 100 } } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "type": { "description": "For folders is 'folder'.", "type": "string" }, "id": { "description": "The folder’s ID.", "type": "string" }, "sequence_id": { "description": "A unique ID for use with the /events endpoint.", "type": "string" }, "etag": { "description": "A unique string identifying the version of this folder.", "type": "string" }, "name": { "description": "The name of the folder.", "type": "string" }, "created_at": { "description": "The time the folder was created.", "type": "timestamp" }, "modified_at": { "description": "The time the folder or its contents were last modified.", "type": "timestamp" }, "description": { "description": "The description of the folder.", "type": "string" }, "size": { "description": "The folder size in bytes.", "type": "integer" }, "path_collection": { "paths": { "properties": { "total_count": { "type": "integer" }, "entries": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "description": "Array of entries.", "type": "array" }, "type": "object" }, "description": "Array of paths.", "type": "array" }, "created_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who created this folder.", "type": "object" }, "modified_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who last modified this folder.", "type": "object" }, "owned_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "description": "The user who owns this folder.", "type": "object" }, "shared_link": { "properties": { "url": { "type": "string" }, "download_url": { "type": "string" }, "vanity_url": { "type": "string" }, "is_password_enabled": { "type": "boolean" }, "unshared_at": { "type": "string" }, "download_count": { "type": "integer" }, "preview_count": { "type": "integer" }, "access": { "type": "string" }, "permissions": { "properties": { "can_download": { "type": "boolean" }, "can_preview": { "type": "boolean" } } } }, "description": "The shared link for this folder.", "type": "object" }, "folder_upload_email": { "properties": { "access": { "type": "string" }, "email": { "type": "string" } }, "description": "The upload email address for this folder.", "type": "object" }, "parent": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "name": { "type": "string" } }, "description": "The folder that contains this one.", "type": "object" }, "item_status": { "description": "Whether this item is deleted or not.", "type": "string" }, "item_collection": { "items": { "properties": { "total_count": { "type": "integer" }, "entries": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "sha1": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "description": "Array of entries", "type": "array" }, "type": "object" }, "description": "A collection of mini file and folder objects contained in this folder.", "type": "array" }, "sync_state": { "description": "Whether this folder will be synced by the Box sync clients or not.", "required": false, "enum": [ "synced", "not_synced", "partially_synced" ] }, "has_collaborations": { "description": "Whether this folder has any collaborators.", "required": false, "type": "boolean" } }, "type": "object" } /email_aliases: type: base get: description: | Get All Email Aliases for a User. Retrieves all email aliases for this user. The collection of email aliases does not include the primary login for the user; use GET /users/USER_ID to retrieve the login email address. If the user_id is valid a collection of email aliases will be returned. responses: 200: body: example: | { "total_count": 1, "entries": [ { "type": "email_alias", "id": "1234", "is_confirmed": true, "email": "dglover2@box.com" }, { "type": "email_alias", "id": "1235", "is_confirmed": true, "email": "dglover3@box.com" } ] } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "total_count": { "type": "integer" }, "entries": [ { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "is_confirmed": { "type": "boolean" }, "email": { "type": "string" } }, "type": "object" } ], "type": "array" } } post: description: | Add an Email Alias for a User. Adds a new email alias to the given user’s account. Returns the newly created email_alias object. Errors will be thrown if the user_id is not valid or the particular user’s email alias cannot be modified. body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "email": { "description": "The email address to add to the account as an alias.", "type": "string" } }, "required": [ "email" ] } responses: 201: body: example: | { "type":"email_alias", "id":"1234", "is_confirmed":true, "email": "dglover2@box.com" } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "is_confirmed": { "type": "boolean" }, "email": { "type": "string" } } } /{emailAliasId}: type: base delete: description: | Removes an email alias from a user. If the user has permission to remove this email alias, an empty 204 No Content response will be returned to confirm deletion. responses: 204: description: Email alias removed. /tasks: type: base post: description: | Create a Task. Used to create a single task for single user on a single file. A new task object will be returned upon success. body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "item": { "description": "The item this task is for.", "type": "object" }, "type": { "description": "The type of the item this task is for (currently only 'file' is supported).", "type": "string" }, "id": { "description": "The ID of the item this task is for.", "type": "string" }, "action": { "description": "The action the task assignee will be prompted to do. Must be 'review'.", "type": [ "review" ] }, "message": { "description": "An optional message to include with the task.", "type": "string" }, "due_at": { "description": "The day at which this task is due.", "type": "timestamp" } }, "required": [ "item", "type", "id", "action" ] } responses: 200: body: example: | { "type": "task", "id": "1839355", "item": { "type": "file", "id": "7287087200", "sequence_id": "0", "etag": "0", "sha1": "0bbd79a105c504f99573e3799756debba4c760cd", "name": "box-logo.png" }, "due_at": "2014-04-03T11:09:43-07:00", "action": "review", "message": "REVIEW PLZ K THX", "task_assignment_collection": { "total_count": 0, "entries": [] }, "is_completed": false, "created_by": { "type": "user", "id": "11993747", "name": "??? sean ???", "login": "sean@box.com" }, "created_at": "2013-04-03T11:12:54-07:00" } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "type": { "descriptipon": "For tasks is 'task'.", "type": "string" }, "id": { "descriptipon": "The unique ID of this task.", "type": "string" }, "item": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "sha1": { "type": "string" }, "name": { "type": "string" } }, "descriptipon": "The file associated with this task.", "type": "object" }, "due_at": { "descriptipon": "The date at which this task is due.", "type": "timestamp" }, "action": { "descriptipon": "The action the task assignee will be prompted to do. Must be 'review'", "type": "string" }, "message": { "descriptipon": "A message that will be included with this task.", "type": "string" }, "task_assignment_collection": { "tasks": { "properties": { "total_count": { "type": "integer" }, "entries": [ { "type": "object" } ], "type": "array" }, "type": "object" }, "type": "array" }, "is_completed": { "type": "boolean" }, "created_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "type": "object" }, "created_at": { "type": "timestamp" } } } /{taskId}: type: base get: description: Fetches a specific task. responses: 200: body: example: | { "total_count": 1, "entries": [ { "type": "task_assignment", "id": "2485961", "item": { "type": "file", "id": "7287087200", "sequence_id": "0", "etag": "0", "sha1": "0bbd79a105c504f99573e3799756debba4c760cd", "name": "box-logo.png" }, "assigned_to": { "type": "user", "id": "193425559", "name": "Rhaegar Targaryen", "login": "rhaegar@box.com" } } ] } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "type": { "descriptipon": "For tasks is 'task'.", "type": "string" }, "id": { "descriptipon": "The unique ID of this task.", "type": "string" }, "item": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "sha1": { "type": "string" }, "name": { "type": "string" } }, "descriptipon": "The file associated with this task.", "type": "object" }, "due_at": { "descriptipon": "The date at which this task is due.", "type": "timestamp" }, "action": { "descriptipon": "The action the task assignee will be prompted to do. Must be 'review'", "type": "string" }, "message": { "descriptipon": "A message that will be included with this task.", "type": "string" }, "task_assignment_collection": { "tasks": { "properties": { "total_count": { "type": "integer" }, "entries": [ { "type": "object" } ], "type": "array" }, "type": "object" }, "type": "array" }, "is_completed": { "type": "boolean" }, "created_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "type": "object" }, "created_at": { "type": "timestamp" } } } put: description: Updates a specific task. body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "action": { "description": "The action the task assignee will be prompted to do. Can be 'review'.", "type": "string" }, "message": { "description": "An optional message to include with the task.", "type": "string" }, "due_at": { "description": "The day at which this task is due.", "type": "timestamp" } } } responses: 200: body: example: | { "type": "task", "id": "1839355", "item": { "type": "file", "id": "7287087200", "sequence_id": "0", "etag": "0", "sha1": "0bbd79a105c504f99573e3799756debba4c760cd", "name": "box-logo.png" }, "due_at": "2014-04-03T11:09:43-07:00", "action": "review", "message": "REVIEW PLZ K THX", "task_assignment_collection": { "total_count": 0, "entries": [] }, "is_completed": false, "created_by": { "type": "user", "id": "11993747", "name": "??? sean ???", "login": "sean@box.com" }, "created_at": "2013-04-03T11:12:54-07:00" } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "type": { "descriptipon": "For tasks is 'task'.", "type": "string" }, "id": { "descriptipon": "The unique ID of this task.", "type": "string" }, "item": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "sha1": { "type": "string" }, "name": { "type": "string" } }, "descriptipon": "The file associated with this task.", "type": "object" }, "due_at": { "descriptipon": "The date at which this task is due.", "type": "timestamp" }, "action": { "descriptipon": "The action the task assignee will be prompted to do. Must be 'review'", "type": "string" }, "message": { "descriptipon": "A message that will be included with this task.", "type": "string" }, "task_assignment_collection": { "tasks": { "properties": { "total_count": { "type": "integer" }, "entries": [ { "type": "object" } ], "type": "array" }, "type": "object" }, "type": "array" }, "is_completed": { "type": "boolean" }, "created_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "type": "object" }, "created_at": { "type": "timestamp" } } } delete: description: | Permanently deletes a specific task. An empty 204 response will be returned upon success. responses: 204: description: Task deleted. /assignments: type: base get: description: | Retrieves all of the assignments for a given task. A collection of task assignment mini objects will be returned upon success. responses: 200: body: example: | { "total_count": 1, "entries": [ { "type": "task_assignment", "id": "2485961", "item": { "type": "file", "id": "7287087200", "sequence_id": "0", "etag": "0", "sha1": "0bbd79a105c504f99573e3799756debba4c760cd", "name": "box-logo.png" }, "assigned_to": { "type": "user", "id": "193425559", "name": "Rhaegar Targaryen", "login": "rhaegar@box.com" } } ] } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object", "properties": { "total_count": { "type": "string" }, "entries": [ { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "item": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "sha1": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "assigned_to": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "type": "object" } }, "type": "object" } ], "type": "array" } } /task_assignments: type: base post: description: | Used to assign a task to a single user. There can be multiple assignments on a given task. A new task assignment object will be returned upon success. body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "task": { "description": "The task this assignment is for.", "type": "object" }, "type": { "description": "Must be 'task'", "type": [ "task" ] }, "id": { "description": "The ID of the task this assignment is for.", "type": "string" }, "assign_to": { "description": "The user this assignment is for. At least one of 'id' or 'login' is required in this object.", "type": "object" }, "id": { "description": "The ID of the user this assignment is for.", "type": "string" }, "login": { "description": "The login email address for the user this assignment is for.", "type": "string" } }, "required": [ "task", "id", "assign_to" ] } responses: 200: body: example: | { "type": "task_assignment", "id": "2698512", "item": { "type": "file", "id": "8018809384", "sequence_id": "0", "etag": "0", "sha1": "7840095ee096ee8297676a138d4e316eabb3ec96", "name": "scrumworksToTrello.js" }, "assigned_to": { "type": "user", "id": "1992432", "name": "rhaegar@box.com", "login": "rhaegar@box.com" }, "message": null, "completed_at": null, "assigned_at": "2013-05-10T11:43:41-07:00", "reminded_at": null, "resolution_state": "incomplete", "assigned_by": { "type": "user", "id": "11993747", "name": "??? sean ???", "login": "sean@box.com" } } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "item": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "sha1": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "assigned_to": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "type": "object" }, "message": { "type": "string" }, "completed_at": { "type": "timestamp" }, "assigned_at": { "type": "timestamp" }, "reminded_at": { "type": "string" }, "resolution_state": { "type": "string" }, "assigned_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "type": "object" } } } /{id}: type: base get: description: | Fetches a specific task assignment. The specified task assignment object will be returned upon success. responses: 200: body: example: | { "type": "task_assignment", "id": "2698512", "item": { "type": "file", "id": "8018809384", "sequence_id": "0", "etag": "0", "sha1": "7840095ee096ee8297676a138d4e316eabb3ec96", "name": "scrumworksToTrello.js" }, "assigned_to": { "type": "user", "id": "1992432", "name": "rhaegar@box.com", "login": "rhaegar@box.com" }, "message": null, "completed_at": null, "assigned_at": "2013-05-10T11:43:41-07:00", "reminded_at": null, "resolution_state": "incomplete", "assigned_by": { "type": "user", "id": "11993747", "name": "??? sean ???", "login": "sean@box.com" } } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "item": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "sha1": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "assigned_to": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "type": "object" }, "message": { "type": "string" }, "completed_at": { "type": "timestamp" }, "assigned_at": { "type": "timestamp" }, "reminded_at": { "type": "string" }, "resolution_state": { "type": "string" }, "assigned_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "type": "object" } } } delete: description: | Deletes a specific task assignment. An empty '204 No Content' response will be returned upon success. responses: 204: description: Task deleted. put: description: | Used to update a task assignment. A new task assignment object will be returned upon success. body: schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "message": { "description": "A message from the assignee about this task.", "type": "string" }, "resolution_state": { "description": "Can be 'completed', 'incomplete', 'approved', or 'rejected'.", "type": [ "completed", "incomplete", "approved", "rejected" ] } } } responses: 200: body: example: | { "type": "task_assignment", "id": "2698512", "item": { "type": "file", "id": "8018809384", "sequence_id": "0", "etag": "0", "sha1": "7840095ee096ee8297676a138d4e316eabb3ec96", "name": "scrumworksToTrello.js" }, "assigned_to": { "type": "user", "id": "1992432", "name": "rhaegar@box.com", "login": "rhaegar@box.com" }, "message": "hello!!!", "completed_at": null, "assigned_at": "2013-05-10T11:43:41-07:00", "reminded_at": null, "resolution_state": "incomplete", "assigned_by": { "type": "user", "id": "11993747", "name": "??? sean ???", "login": "sean@box.com" } } schema: | { "$schema": "http://json-schema.org/draft-03/schema", "type": "object" , "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "item": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "sequence_id": { "type": "string" }, "etag": { "type": "string" }, "sha1": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "assigned_to": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "type": "object" }, "message": { "type": "string" }, "completed_at": { "type": "timestamp" }, "assigned_at": { "type": "timestamp" }, "reminded_at": { "type": "string" }, "resolution_state": { "type": "string" }, "assigned_by": { "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" } }, "type": "object" } } }