openapi-directory/api/box.com/content.json

Building & bundling https://github.com/APIs-guru/openapi-directory for easy use from JS

{"openapi":"3.0.0","info":{"description":"The Box Content API gives you access to secure content management and content experience features for use in your own app. It strives to be RESTful and is organized around the main resources you’re familiar with from the Box web interface.","license":{"name":"Apache 2.0","url":"http://www.apache.org/licenses/LICENSE-2.0"},"title":"Box 2.0","version":"2.0","x-apisguru-categories":["cloud"],"x-logo":{"url":"https://twitter.com/BoxHQ/profile_image?size=original"},"x-origin":[{"format":"swagger","url":"https://raw.githubusercontent.com/box/box-openapi/master/v2.0/openapi-v2.json","version":"2.0"}],"x-providerName":"box.com","x-serviceName":"content"},"security":[{"OAuth2Security":[]}],"tags":[{"description":"Folders operations","name":"Folders"},{"description":"Files operations","name":"Files"},{"description":"Web Links operations","name":"Web Links"},{"description":"Metadata operations","name":"Metadata"},{"description":"Collections operations","name":"Collections"},{"description":"Search operations","name":"Search"},{"description":"Collaborations operations","name":"Collaborations"},{"description":"Shared Items operations","name":"Shared Items"},{"description":"Comments operations","name":"Comments"},{"description":"Tasks operations","name":"Tasks"},{"description":"Events operations","name":"Events"},{"description":"Webhooks operations","name":"Webhooks"},{"description":"Users operations","name":"Users"},{"description":"Groups operations","name":"Groups"},{"description":"Devices operations","name":"Devices"},{"description":"Retention Policies operations","name":"Retention Policies"},{"description":"Legal Holds Policies operations","name":"Legal Holds Policies"}],"paths":{"/collaborations":{"get":{"description":"Used to retrieve all pending collaboration invites for this user.","externalDocs":{"url":"https://docs.box.com/reference#get-pending-collaborations"},"operationId":"getPendingCollaborations","parameters":[{"description":"Attribute(s) to include in the response","in":"query","name":"fields","required":false,"schema":{"type":"string"}},{"description":"Must be 'pending'","in":"query","name":"status","required":true,"schema":{"type":"string","enum":["pending"]}}],"responses":{"200":{"description":"A collection of pending collaboration objects are returned. If the user has no pending collaborations, the collection will be empty.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollaborationList"},"examples":{"response":{"value":{"entries":[{"accessible_by":{"id":"181216415","login":"sean+awesome@box.com","name":"sean rose","type":"user"},"created_at":"2012-10-17T23:14:42-07:00","created_by":{"id":"11993747","login":"sean@box.com","name":"sean","type":"user"},"id":"27513888","modified_at":"2012-10-17T23:14:42-07:00","role":"Editor","status":"Pending","type":"collaboration"}],"total_count":1}}}}}},"default":{"description":"Get pending collaborations operation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Pending Collaborations","tags":["Collaborations"]},"post":{"description":"Used to add a collaboration for a single user or a single group to a folder. Either an email address, a user ID, or a group id can be used to create the collaboration. If the collaboration is being created with a group, access to this endpoint is granted based on the group's invitability_level.","externalDocs":{"url":"https://docs.box.com/reference#add-a-collaboration"},"operationId":"createCollaboration","requestBody":{"$ref":"#/components/requestBodies/Collaboration"},"responses":{"201":{"description":"The new collaboration object is returned. Errors may occur if the IDs are invalid or if the user does not have permissions to create a collaboration.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collaboration"},"examples":{"response":{"value":{"accessible_by":{"id":"18203124","login":"sean+test@box.com","name":"sean","type":"user"},"acknowledged_at":"2012-12-12T11:30:43-08:00","created_at":"2012-12-12T10:54:37-08:00","created_by":{"id":"17738362","login":"sean@box.com","name":"sean rose","type":"user"},"id":"791293","item":{"etag":"0","id":"11446500","name":"Shared Pictures","sequence_id":"0","type":"folder"},"modified_at":"2012-12-12T11:30:43-08:00","role":"editor","status":"accepted","type":"collaboration"}}}}}},"default":{"description":"Add a collaboration operation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Create Collaboration","tags":["Collaborations"]}},"/collaborations/{COLLAB_ID}":{"delete":{"description":"Used to delete a single collaboration.","externalDocs":{"url":"https://docs.box.com/reference#remove-a-collaboration"},"operationId":"deleteCollaboration","parameters":[{"in":"path","name":"COLLAB_ID","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"A blank 204 response is returned if the ID is valid, and the user has permissions to remove the collaboration."},"default":{"description":"Delete a collaboration operation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Delete Collaboration","tags":["Collaborations"]},"get":{"description":"Used to get information about a single collaboration. All collaborations for a single folder can be retrieved through GET /folders/{id}/collaborations. A complete list of the user’s pending collaborations can also be retrieved.","externalDocs":{"url":"https://docs.box.com/reference#get-collabs"},"operationId":"getCollaboration","parameters":[{"in":"path","name":"COLLAB_ID","required":true,"schema":{"type":"string"}},{"description":"Attribute(s) to include in the response","in":"query","name":"fields","required":false,"schema":{"type":"string"}},{"description":"Can only be pending","in":"query","name":"status","required":false,"schema":{"type":"string","enum":["pending"]}}],"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collaboration"}}}},"default":{"description":"Get a collaboration error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Get Collaboration","tags":["Collaborations"]},"put":{"description":"Used to edit an existing collaboration. Descriptions of the various roles can be found here.","externalDocs":{"url":"https://docs.box.com/reference#edit-a-collaboration"},"operationId":"updateCollaboation","parameters":[{"in":"path","name":"COLLAB_ID","required":true,"schema":{"type":"string"}}],"requestBody":{"$ref":"#/components/requestBodies/Collaboration"},"responses":{"200":{"description":"The updated collaboration object is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collaboration"},"examples":{"response":{"value":{"accessible_by":{"id":"18203124","login":"sean+test@box.com","name":"sean","type":"user"},"acknowledged_at":"2012-12-12T11:30:43-08:00","created_at":"2012-12-12T10:54:37-08:00","created_by":{"id":"17738362","login":"sean@box.com","name":"sean rose","type":"user"},"id":"791293","item":{"etag":"0","id":"11446500","name":"Shared Pictures","sequence_id":"0","type":"folder"},"modified_at":"2012-12-12T11:30:43-08:00","role":"viewer","status":"accepted","type":"collaboration"}}}}}},"204":{"description":"If the role is changed to owner, the collaboration is deleted with a new one created for the previous owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collaboration"}}}},"default":{"description":"Update collaboration error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Update Collaboration","tags":["Collaborations"]}},"/collections":{"get":{"description":"Retrieves the collections for the given user. Currently, only the favorites collection is supported.","externalDocs":{"url":"https://docs.box.com/reference#get-collections"},"operationId":"getCollections","responses":{"200":{"description":"Collections for the given user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionList"},"examples":{"response":{"value":{"entries":[{"collection_type":"favorites","id":"405151","name":"Favorites","type":"collection"}],"limit":100,"offset":0,"total_count":1}}}}}},"default":{"description":"Get Collections error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Get Collections","tags":["Collections"]}},"/collections/{COLLECTION_ID}/items":{"get":{"description":"Retrieves the files and/or folders contained within this collection. Collection item lists behave a lot like getting a folder’s items.\nPaginated results can be retrieved using the limit and offset parameters.\nSub-object fields can be requested via the ?fields parameter","externalDocs":{"url":"https://docs.box.com/reference#collections-beta"},"operationId":"getCollectionItems","parameters":[{"in":"path","name":"COLLECTION_ID","required":true,"schema":{"type":"string"}},{"description":"Attribute(s) to include in the response","in":"query","name":"fields","required":false,"schema":{"type":"string"}},{"description":"The maximum number of items to return in a page.","in":"query","name":"limit","required":false,"schema":{"type":"integer","format":"int64"}},{"description":"The offset at which to begin the response. An offset of value of 0 will start at the beginning of the folder-listing. Offset of 2 would start at the 2nd record, not the second page. Note: If there are hidden items in your previous response, your next offset should be = offset + limit, not the # of records you received back.","in":"query","name":"offset","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"An array of items contained in the collection is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemReferenceList"}}}},"default":{"description":"An error is thrown if the collection does not exist, or if any of the parameters are invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Get Collection Items","tags":["Collections"]}},"/comments":{"post":{"description":"Used to add a comment by the user to a specific file or comment (i.e. as a reply comment).","externalDocs":{"url":"https://docs.box.com/reference#add-a-comment-to-an-item"},"operationId":"createComment","parameters":[{"description":"Attribute(s) to include in the response.","in":"query","name":"fields","required":false,"schema":{"type":"string"}}],"requestBody":{"$ref":"#/components/requestBodies/Comment"},"responses":{"201":{"description":"The new comment object is returned. Errors may occur if the item id is invalid, the item type is invalid/unsupported, you don’t include either a message or a tagged_message, or if the user does not have access to the item being commented on.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Comment"},"examples":{"response":{"value":{"created_at":"2012-12-12T11:25:01-08:00","created_by":{"id":"17738362","login":"sean@box.com","name":"sean rose","type":"user"},"id":"191969","is_reply_comment":false,"item":{"id":"5000948880","type":"file"},"message":"These tigers are cool!","modified_at":"2012-12-12T11:25:01-08:00","type":"comment"}}}}}},"default":{"description":"Errors may occur if the item id is invalid, the item type is invalid/unsupported, you don’t include either a message or a tagged_message, or if the user does not have access to the item being commented on.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Create Comment","tags":["Comments"]}},"/comments/{COMMENT_ID}":{"delete":{"description":"Permanently deletes a comment.","externalDocs":{"url":"https://docs.box.com/reference#delete-a-comment"},"operationId":"deleteComment","parameters":[{"in":"path","name":"COMMENT_ID","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"An empty 204 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."},"default":{"description":"Errors can be thrown if the ID is invalid or if the user is not authorized to delete this particular comment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Delete Comment","tags":["Comments"]},"get":{"description":"Used to retrieve the message and metadata about a specific comment. Information about the user who created the comment is also included.","externalDocs":{"url":"https://docs.box.com/reference#comments"},"operationId":"getComment","parameters":[{"in":"path","name":"COMMENT_ID","required":true,"schema":{"type":"string"}},{"description":"Attribute(s) to include in the response.","in":"query","name":"fields","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"A full comment object is returned is the ID is valid and if the user has access to the comment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Comment"},"examples":{"response":{"value":{"created_at":"2012-12-12T11:25:01-08:00","created_by":{"id":"17738362","login":"sean@box.com","name":"sean rose","type":"user"},"id":"191969","is_reply_comment":false,"item":{"id":"5000948880","type":"file"},"message":"These tigers are cool!","modified_at":"2012-12-12T11:25:01-08:00","type":"comment"}}}}}},"default":{"description":"Get comment error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Get Comment","tags":["Comments"]},"put":{"description":"Used to update the message of the comment.","externalDocs":{"url":"https://docs.box.com/reference#change-a-comments-message"},"operationId":"updateComment","parameters":[{"in":"path","name":"COMMENT_ID","required":true,"schema":{"type":"string"}},{"description":"Attribute(s) to include in the response.","in":"query","name":"fields","required":false,"schema":{"type":"string"}}],"requestBody":{"$ref":"#/components/requestBodies/Comment"},"responses":{"200":{"description":"The full updated comment object is returned if the ID is valid and if the user has access to the comment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Comment"},"examples":{"response":{"value":{"created_at":"2012-12-12T11:25:01-08:00","created_by":{"id":"17738362","login":"sean@box.com","name":"sean rose","type":"user"},"id":"191969","is_reply_comment":false,"item":{"id":"5000948880","type":"file"},"message":"These tigers are cool!","modified_at":"2012-12-12T11:25:01-08:00","type":"comment"}}}}}},"default":{"description":"Update comment error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Update Comment","tags":["Comments"]}},"/device_pinners/{ID}":{"delete":{"description":"Delete individual device pin.","externalDocs":{"url":"https://docs.box.com/reference#delete-device-pin"},"operationId":"deleteDevicePin","parameters":[{"in":"path","name":"ID","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"A 204 will be returned if deletion is successful"},"default":{"description":"Delete device pinner error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Delete Device Pin","tags":["Devices"]},"get":{"description":"Gets information about an individual device pin.","externalDocs":{"url":"https://docs.box.com/reference#get-device-pin"},"operationId":"getDevicePin","parameters":[{"in":"path","name":"ID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returns information about a single device pin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DevicePinner"},"examples":{"response":{"value":{"created_at":"2014-09-23T22:56:18-07:00","id":"788804","modified_at":"2014-09-23T22:56:18-07:00","owned_by":{"id":"222276603","login":"ted+boxworks2@box.com","name":"Ted Blosser","type":"user"},"product_name":"iPad","type":"device_pinner"}}}}}},"default":{"description":"Get device pinner error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Get Device Pin","tags":["Devices"]}},"/enterprises/{ENTERPRISE_ID}/device_pinners":{"get":{"description":"Gets all the device pins within a given enterprise. Must be an enterprise admin with the manage enterprise scope to make this call.","externalDocs":{"url":"https://docs.box.com/reference#get-device-pins"},"operationId":"getEnterpriseDevicePins","parameters":[{"in":"path","name":"ENTERPRISE_ID","required":true,"schema":{"type":"string"}},{"description":"Needs not be passed or can be empty for first invocation of the API. Use the one returned in response for each subsequent call.","in":"query","name":"marker","required":false,"schema":{"type":"string"}},{"description":"Default value is 100. Max value is 10000","in":"query","name":"limit","required":false,"schema":{"type":"string"}},{"description":"Default is \"asc\". Valid values are asc, desc. Case in-sensitive, ASC/DESC works just fine.","in":"query","name":"direction","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returns a list of device pins for a given enterprise.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DevicePinnerList"},"examples":{"response":{"value":{"entries":[{"id":"788804","owned_by":{"id":"222276603","login":"ted+boxworks2@box.com","name":"Ted Blosser","type":"user"},"product_name":"iPad","type":"device_pinner"},{"id":"1003086","owned_by":{"id":"222276603","login":"ted+boxworks2@box.com","name":"Ted Blosser","type":"user"},"product_name":"iPhone","type":"device_pinner"}],"limit":100,"order":[{"by":"id","direction":"ASC"}]}}}}}},"default":{"description":"Get device pinners for an enterprise error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Get Enterprise Device Pins","tags":["Devices"]}},"/events":{"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.\n\nTo retrieve Enterprise Events specify 'stream_type=admin_logs'. Retrieves up to a year' events for all users in an enterprise. Upper and lower bounds as well as filters can be applied to the results.","externalDocs":{"url":"https://docs.box.com/reference#get-events-for-a-user"},"operationId":"getUserEvents","parameters":[{"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.","in":"query","name":"stream_position","required":false,"schema":{"type":"string"}},{"description":"Limits the type of events returned: all: returns everything, changes: returns tree changes, sync: returns tree changes only for sync folders","in":"query","name":"stream_type","required":false,"schema":{"type":"string","enum":["all","changes","sync","admin_logs"]}},{"description":"Limits the number of events returned","in":"query","name":"limit","required":false,"schema":{"type":"integer","format":"int64"}},{"description":"A comma-separated list of events to filter by","in":"query","name":"event_type","required":false,"schema":{"type":"string"}},{"description":"A lower bound on the timestamp of the events returned","in":"query","name":"created_after","required":false,"schema":{"type":"string","format":"date-time"}},{"description":"An upper bound on the timestamp of the events returned","in":"query","name":"created_before","required":false,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"A collection of events is returned. See the above table for descriptions of the event types.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventList"},"examples":{"response":{"value":{"chunk_size":1,"entries":[{"created_at":"2012-12-12T10:53:43-08:00","created_by":{"id":"17738362","login":"sean@box.com","name":"sean rose","type":"user"},"event_id":"f82c3ba03e41f7e8a7608363cc6c0390183c3f83","event_type":"ITEM_CREATE","recorded_at":"2012-12-12T10:53:48-08:00","session_id":"70090280850c8d2a1933c1","source":{"created_at":"2012-12-12T10:53:43-08:00","created_by":{"id":"17738362","login":"sean@box.com","name":"sean rose","type":"user"},"etag":"0","id":"11446498","item_status":"active","modified_at":"2012-12-12T10:53:43-08:00","modified_by":{"id":"17738362","login":"sean@box.com","name":"sean rose","type":"user"},"name":"Pictures","owned_by":{"id":"17738362","login":"sean@box.com","name":"sean rose","type":"user"},"parent":{"id":"0","name":"All Files","type":"folder"},"sequence_id":"0","size":0,"synced":false,"type":"folder"},"type":"event"}],"next_stream_position":1348790499819}}}}}},"default":{"description":"Get events error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"User Events, Enterprise Events","tags":["Events"]},"options":{"description":"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.\nIf 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.\nIf you receive no events in retry_timeout seconds, you should make another GET request to the real time server (i.e. URL in the response). This might be necessary in case you do not receive the reconnect message in the face of network errors.\nIf you receive max_retries error when making GET requests to the real time server, you should make another OPTIONS request.","externalDocs":{"url":"https://docs.box.com/reference#long-polling"},"operationId":"eventLongPolling","responses":{"200":{"description":"Paginated array of Realtime server instances","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RealtimeServerList"}}}},"default":{"description":"Options Long polling error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Long polling","tags":["Events"]}},"/file_version_legal_holds":{"get":{"description":"Get list of non-deleted Holds for a single Policy.","externalDocs":{"url":"https://docs.box.com/reference#get-list-of-file-version-legal-holds"},"operationId":"getFileVersionLegalHoldPolicies","parameters":[{"in":"query","name":"policy_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returns the list of File Version Legal Holds for the passed in Policy. By default, will only return only type, and id, but you can specify more by using the fields parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileVersionLegalHoldList"}}}},"default":{"description":"Get File Version Legal Hold policy error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Get List of File Version Legal Holds","tags":["Legal Hold Policies"]}},"/file_version_legal_holds/{ID}":{"get":{"description":"Get details of a single File Version Legal Hold.","externalDocs":{"url":"https://docs.box.com/reference#get-hold-by-id"},"operationId":"getFileVersionLegalHoldPolicy","parameters":[{"in":"path","name":"ID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"If the ID is valid, information about the Hold is returned with a 200.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileVersionLegalHold"}}}},"404":{"description":"If the ID is for a non-existent Hold, a 404 is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Get File Version Legal Hold policy error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Get File Version Legal Hold","tags":["Legal Hold Policies"]}},"/file_version_retentions":{"get":{"description":"Retrieves all file version retentions for the given enterprise.","externalDocs":{"url":"https://docs.box.com/reference#get-file-version-retentions"},"operationId":"getFileVersionRetentions","parameters":[{"description":"A file id to filter the file version retentions by.","in":"query","name":"file_id","required":false,"schema":{"type":"string"}},{"description":"A file version id to filter the file version retentions by.","in":"query","name":"file_version_id","required":false,"schema":{"type":"string"}},{"description":"A policy id to filter the file version retentions by.","in":"query","name":"policy_id","required":false,"schema":{"type":"string"}},{"description":"The disposition action of the retention policy. This action can be permanently_delete, which will cause the content retained by the policy to be permanently deleted, or remove_retention, which will lift the retention policy from the content, allowing it to be deleted by users, once the retention policy time period has passed.","in":"query","name":"disposition_action","required":false,"schema":{"type":"string","enum":["permanently_delete","remove_retention"]}},{"description":"See content times for formatting","in":"query","name":"disposition_before","required":false,"schema":{"type":"string"}},{"description":"See content times for formatting","in":"query","name":"disposition_after","required":false,"schema":{"type":"string"}},{"description":"The maximum number of items to return in a page","in":"query","name":"limit","required":false,"schema":{"type":"integer","format":"int64"}},{"description":"Base 64 encoded string that represents where the paging should being. It should be left blank to begin paging.","in":"query","name":"marker","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returns the list of all file version retentions for the enterprise. If the query parameters are given, only the file version retentions that match the query parameters are returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileVersionRetentionList"},"examples":{"response":{"value":{"entries":[{"id":"112725","type":"file_version_retention"},{"id":"112729","type":"file_version_retention"},{"id":"112733","type":"file_version_retention"}],"limit":100,"order":[{"by":"file_version_id","direction":"ASC"}]}}}}}},"default":{"description":"Get File version retentions error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Get File Version Retentions","tags":["Files"]}},"/file_version_retentions/{FILE_VERSION_RETENTION_ID}":{"get":{"description":"Used to retrieve information about a file version retention","externalDocs":{"url":"https://docs.box.com/reference#get-file-version-retention"},"operationId":"getFileVersionRetention","parameters":[{"in":"path","name":"FILE_VERSION_RETENTION_ID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The specified file version retention will be returned upon success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileVersionRetention"},"examples":{"response":{"value":{"applied_at":"2015-08-06T22:02:24-07:00","disposition_at":"2016-08-06T21:45:28-07:00","file":{"etag":"2","id":"5011706273","type":"file_version"},"file_version":{"id":"124887629","sha1":"4262d6250b0e6f440dca43a2337bd4621bad9136","type":"file_version"},"id":"112729","type":"file_version_retention","winning_retention_policy":{"id":"41173","policy_name":"Tax Documents","type":"retention_policy"}}}}}}},"404":{"description":"If the file version retention specified does not exist, a 404 HTTP status code of not_found is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Get file version Retention error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Get File Version Retention","tags":["Files"]}},"/files/content":{"options":{"description":"The Pre-flight check API will verify that a file will be accepted by Box before you send all the bytes over the wire.","externalDocs":{"url":"https://docs.box.com/reference#preflight-check"},"operationId":"fileUploadPreflightCheck","requestBody":{"$ref":"#/components/requestBodies/BoxFile"},"responses":{"200":{"description":"The upload would be successful"},"default":{"description":"File upload preflight check error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"File upload preflight check","tags":["Files"]}},"/files/{FILE_ID}":{"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.","externalDocs":{"url":"https://docs.box.com/reference#delete-a-file"},"operationId":"deleteFile","parameters":[{"in":"path","name":"FILE_ID","required":true,"schema":{"type":"string"}},{"description":"The etag of the file. This is in the ‘etag’ field of the file object.","in":"header","name":"If-Match","required":false,"schema":{"type":"string"}}],"responses":{"204":{"description":"An empty 204 response is sent to confirm deletion of the file."},"412":{"description":"If the If-Match header is sent and fails, a 412 Precondition Failed error is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Delete file error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Delete File","tags":["Files"]},"get":{"description":"Used to retrieve the metadata about a file.","externalDocs":{"url":"https://docs.box.com/reference#files"},"operationId":"getFile","parameters":[{"in":"path","name":"FILE_ID","required":true,"schema":{"type":"string"}},{"description":"Attribute(s) to include in the response.","in":"query","name":"fields","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"A full file object is returned if the ID is valid and if the user has access to the file.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoxFile"},"examples":{"response":{"value":{"created_at":"2012-12-12T10:55:30-08:00","created_by":{"id":"17738362","login":"sean@box.com","name":"sean rose","type":"user"},"description":"a picture of tigers","etag":"3","file_version":{"id":"26261748416","sha1":"134b65991ed521fcfe4724b7d814ab8ded5185dc","type":"file_version"},"id":"5000948880","item_status":"active","modified_at":"2012-12-12T11:04:26-08:00","modified_by":{"id":"17738362","login":"sean@box.com","name":"sean rose","type":"user"},"name":"tigers.jpeg","owned_by":{"id":"17738362","login":"sean@box.com","name":"sean rose","type":"user"},"parent":{"etag":"1","id":"11446498","name":"Pictures","sequence_id":"1","type":"folder"},"path_collection":{"entries":[{"id":"0","name":"All Files","type":"folder"},{"etag":"1","id":"11446498","name":"Pictures","sequence_id":"1","type":"folder"}],"total_count":2},"sequence_id":"3","sha1":"134b65991ed521fcfe4724b7d814ab8ded5185dc","shared_link":{"access":"open","download_count":0,"download_url":"https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg","is_password_enabled":false,"permissions":{"can_download":true,"can_preview":true},"preview_count":0,"url":"https://www.box.com/s/rh935iit6ewrmw0unyul"},"size":629644,"type":"file"}}}}}},"404":{"description":"File Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Media Type Not Supported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Get file info error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Get File's Info, Get Embed Link","tags":["Files"]},"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.","externalDocs":{"url":"https://docs.box.com/reference#restore-a-trashed-item"},"operationId":"restoreTrashedFile","parameters":[{"in":"path","name":"FILE_ID","required":true,"schema":{"type":"string"}}],"requestBody":{"$ref":"#/components/requestBodies/BoxFile"},"responses":{"201":{"description":"The full item will be returned with a 201 Created status. By default it is restored to the parent folder it was in before it was trashed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoxFile"},"examples":{"response":{"value":{"content_created_at":"2013-01-30T18:43:56-08:00","content_modified_at":"2013-02-07T10:56:58-08:00","created_at":"2013-01-30T18:43:56-08:00","created_by":{"id":"181757341","login":"sean+test@box.com","name":"sean test","type":"user"},"description":"","etag":"3","id":"5859258256","item_status":"active","modified_at":"2013-02-07T10:56:58-08:00","modified_by":{"id":"181757341","login":"sean+test@box.com","name":"sean test","type":"user"},"name":"Screenshot_1_30_13_6_37_PM.png","owned_by":{"id":"181757341","login":"sean+test@box.com","name":"sean test","type":"user"},"parent":{"id":"0","name":"All Files","type":"folder"},"path_collection":{"entries":[{"id":"0","name":"All Files","type":"folder"}],"total_count":1},"sequence_id":"3","sha1":"4bd9e98652799fc57cf9423e13629c151152ce6c","shared_link":{"access":"open","download_count":0,"download_url":"https://seanrose.box.com/shared/static/ebgti08mtmhbpb4vlp55.png","is_password_enabled":false,"permissions":{"can_download":true,"can_preview":true},"preview_count":4,"url":"https://seanrose.box.com/s/ebgti08mtmhbpb4vlp55"},"size":163265,"type":"file"}}}}}},"403":{"description":"The user doesn’t have access to the folder the item is being restored to or the user doesn’t have permission to restore items from the trash","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The item is not in the trash","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"There is an item with the same name in the folder the item is being restored to","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Restore file error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Restore Item","tags":["Files"]},"put":{"description":"Used to update individual or multiple fields in the file object, including renaming the file, changing its 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 prevent race conditions.\n\nTo lock and unlock files, you execute a PUT operation on the /files/{file id} endpoint and set or clear the lock properties on the file.\n\nUsed to create a shared link for this particular file. Please see here for more information on the permissions available for shared links. In order to get default shared link status, set it to an empty access level, i.e. {\"shared_link\": {}}. In order to disable a shared link, send this same type of PUT request with the value of shared_link set to null, i.e. {\"shared_link\": null}","externalDocs":{"url":"https://docs.box.com/reference#update-a-files-information"},"operationId":"updateFileInfo","parameters":[{"in":"path","name":"FILE_ID","required":true,"schema":{"type":"string"}},{"description":"The etag of the file can be included as an ‘If-Match’ header to prevent race conditions.","in":"header","name":"If-Match","required":false,"schema":{"type":"string"}}],"requestBody":{"$ref":"#/components/requestBodies/BoxFile"},"responses":{"200":{"description":"A full file object is returned if the ID is valid and if the user has access to the file.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoxFile"},"examples":{"response":{"value":{"created_at":"2012-12-12T10:55:30-08:00","created_by":{"id":"17738362","login":"sean@box.com","name":"sean rose","type":"user"},"description":"a picture of tigers","etag":"3","id":"5000948880","item_status":"active","modified_at":"2012-12-12T11:04:26-08:00","modified_by":{"id":"17738362","login":"sean@box.com","name":"sean rose","type":"user"},"name":"new name.jpg","owned_by":{"id":"17738362","login":"sean@box.com","name":"sean rose","type":"user"},"parent":{"etag":"1","id":"11446498","name":"Pictures","sequence_id":"1","type":"folder"},"path_collection":{"entries":[{"id":"0","name":"All Files","type":"folder"},{"etag":"1","id":"11446498","name":"Pictures","sequence_id":"1","type":"folder"}],"total_count":2},"sequence_id":"3","sha1":"134b65991ed521fcfe4724b7d814ab8ded5185dc","shared_link":{"access":"open","download_count":0,"download_url":"https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg","is_password_enabled":false,"permissions":{"can_download":true,"can_preview":true},"preview_count":0,"url":"https://www.box.com/s/rh935iit6ewrmw0unyul"},"size":629644,"type":"file"}}}}}},"default":{"description":"Update file info error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Update File Info, Lock and Unlock, Create Shared Link","tags":["Files"]}},"/files/{FILE_ID}/collaborations":{"get":{"description":"Use this to get a list of all the collaborations on a file","externalDocs":{"url":"https://docs.box.com/reference#get-file-collaborations"},"operationId":"getFileCollaborations","parameters":[{"in":"path","name":"FILE_ID","required":true,"schema":{"type":"string"}},{"description":"Attribute(s) to include in the response","in":"query","name":"fields","required":false,"schema":{"type":"string"}},{"description":"The maximum number of items to return in a page","in":"query","name":"limit","required":false,"schema":{"type":"integer","format":"int32"}},{"description":"The item at which to begin the response","in":"query","name":"offset","required":false,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"A collection of collaboration objects is returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollaborationList"},"examples":{"response":{"value":{"entries":[{"created_at":"2012-12-12T11:25:01-08:00","created_by":{"id":"17738362","login":"sean@box.com","name":"sean rose","type":"user"},"id":"191969","is_reply_comment":false,"item":{"id":"5000948880","type":"file"},"message":"These tigers are cool!","modified_at":"2012-12-12T11:25:01-08:00","type":"comment"}],"total_count":1}}}}}},"default":{"description":"Get File's Collaborations error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Get File's Collaborations","tags":["Files"]}},"/files/{FILE_ID}/comments":{"get":{"description":"Retrieves the comments on a particular file, if any exist.","externalDocs":{"url":"https://docs.box.com/reference#view-the-comments-on-a-file"},"operationId":"getFileComments","parameters":[{"in":"path","name":"FILE_ID","required":true,"schema":{"type":"string"}},{"description":"Attribute(s) to include in the response","in":"query","name":"fields","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"A collection of comment objects are returned. If there are no comments on the file, an empty comments array is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentList"},"examples":{"response":{"value":{"entries":[{"created_at":"2012-12-12T11:25:01-08:00","created_by":{"id":"17738362","login":"sean@box.com","name":"sean rose","type":"user"},"id":"191969","is_reply_comment":false,"item":{"id":"5000948880","type":"file"},"message":"These tigers are cool!","modified_at":"2012-12-12T11:25:01-08:00","type":"comment"}],"total_count":1}}}}}},"default":{"description":"Get file's comments error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Get File's Comments","tags":["Files"]}},"/files/{FILE_ID}/content":{"get":{"description":"Retrieves the actual data of the file. An optional version parameter can be set to download a previous version of the file.","externalDocs":{"url":"https://docs.box.com/reference#download-a-file"},"operationId":"getFileContent","parameters":[{"in":"path","name":"FILE_ID","required":true,"schema":{"type":"string"}},{"description":"The range value in bytes. Format should be bytes={start_range}-{end_range}","in":"header","name":"Range","required":false,"schema":{"type":"string"}},{"description":"The ID specific version of this file to download.","in":"query","name":"version","required":false,"schema":{"type":"string"}},{"description":"The shared link for this item. Format should be shared_link=SHARED_LINK","in":"header","name":"BoxApi","required":false,"schema":{"type":"string"}}],"responses":{"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."},"302":{"description":"If the file is available to be downloaded, the response will be a 302 Found to a URL at dl.boxcloud.com. The dl.boxcloud.com URL is not persistent. Clients will need to follow the redirect in order to actually download the file. The raw data of the file is returned unless the file ID is invalid or the user does not have access to it."},"default":{"description":"Download file error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Download File","tags":["Files"]}},"/files/{FILE_ID}/copy":{"post":{"description":"Used to create a copy of a file in another folder. The original version of the file will not be altered.","externalDocs":{"url":"https://docs.box.com/reference#copy-a-file"},"operationId":"copyFile","parameters":[{"in":"path","name":"FILE_ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CopyFile"}}},"required":true},"responses":{"201":{"description":"A full file object is returned if the ID is valid and if the update is successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoxFile"},"examples":{"response":{"value":{"created_at":"2012-12-12T10:55:30-08:00","created_by":{"id":"17738362","login":"sean@box.com","name":"sean rose","type":"user"},"description":"a picture of tigers","etag":"3","id":"5000948880","item_status":"active","modified_at":"2012-12-12T11:04:26-08:00","modified_by":{"id":"17738362","login":"sean@box.com","name":"sean rose","type":"user"},"name":"tigers.jpeg","owned_by":{"id":"17738362","login":"sean@box.com","name":"sean rose","type":"user"},"parent":{"etag":"1","id":"11446498","name":"Pictures","sequence_id":"1","type":"folder"},"path_collection":{"entries":[{"id":"0","name":"All Files","type":"folder"},{"etag":"1","id":"11446498","name":"Pictures","sequence_id":"1","type":"folder"}],"total_count":2},"sequence_id":"3","sha1":"134b65991ed521fcfe4724b7d814ab8ded5185dc","shared_link":{"access":"open","download_count":0,"download_url":"https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg","is_password_enabled":false,"permissions":{"can_download":true,"can_preview":true},"preview_count":0,"url":"https://www.box.com/s/rh935iit6ewrmw0unyul"},"size":629644,"type":"file"}}}}}},"409":{"description":"A 409 will be returned if the intended destination folder is the same, as this will cause a name collision.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Copy file error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Copy File","tags":["Files"]}},"/files/{FILE_ID}/metadata":{"get":{"description":"Used to retrieve all metadata associated with a given file","externalDocs":{"url":"https://docs.box.com/reference#create-web-link"},"operationId":"getAllFileMetadata","parameters":[{"in":"path","name":"FILE_ID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"An array of metadata instances associated with the file.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetadataList"},"examples":{"response":{"value":{"entries":[{"$id":"50ba0dba-0f89-4395-b867-3e057c1f6ed9","$parent":"file_5010739061","$scope":"enterprise_12345","$template":"documentFlow","$type":"documentFlow-452b4c9d-c3ad-4ac7-b1ad-9d5192f2fc5f","$typeVersion":2,"$version":4,"currentDocumentStage":"Init","needsApprovalFrom":"Smith"},{"$id":"15d1014a-06c2-47ad-9916-014eab456194","$parent":"file_5010739061","$scope":"enterprise_12345","$template":"productInfo","$type":"productInfo-9d7b6993-b09e-4e52-b197-e42f0ea995b9","$typeVersion":1,"$version":2,"description":"Watch","skuNumber":45334223},{"$id":"b6f36cbc-fc7a-4eda-8889-130f350cc057","$parent":"file_5010739061","$scope":"global","$template":"properties","$type":"properties","$typeVersion":2,"$version":0,"Popularity":"25"}],"limit":100}}}}}}},"summary":"Get all Metadata on File","tags":["Metadata"]}},"/files/{FILE_ID}/metadata/{SCOPE}/{TEMPLATE}":{"delete":{"description":"Used to delete the template instance. To delete custom key:value pairs within a template instance, you should refer to the updating metadata section.","externalDocs":{"url":"https://docs.box.com/reference#delete-metadata"},"operationId":"deleteFileMetadata","parameters":[{"in":"path","name":"FILE_ID","required":true,"schema":{"type":"string"}},{"in":"path","name":"SCOPE","required":true,"schema":{"type":"string"}},{"in":"path","name":"TEMPLATE","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"An empty HTTP 204 response to confirm the deletion of the template instance."},"default":{"description":"Delete file metadata error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Delete Metadata on File","tags":["Metadata"]},"get":{"description":"Used to retrieve the metadata template instance for a corresponding Box file.","externalDocs":{"url":"https://docs.box.com/reference#get-metadata"},"operationId":"getFileMetadata","parameters":[{"in":"path","name":"FILE_ID","required":true,"schema":{"type":"string"}},{"in":"path","name":"SCOPE","required":true,"schema":{"type":"string"}},{"in":"path","name":"TEMPLATE","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"An instance of the template that includes key:value pairs defined by a user or application.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Metadata"},"examples":{"response":{"value":{"$id":"2094c584-68e1-475c-a581-534a4609594e","$parent":"file_5010739061","$scope":"enterprise_12345","$template":"marketingCollateral","$type":"marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe","$typeVersion":0,"$version":0,"audience1":"internal","author":"Jones","competitiveDocument":"no","currentState":"proposal","documentType":"Q1 plans","status":"active"}}}}}},"404":{"description":"If there is no template instance present, a 404 HTTP status code of not_found will be returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Get File metdata error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"summary":"Get Metadata on File","tags":["Metadata"]},"post":{"description":"Used to create the metadata template instance for a corresponding Box file. When creating metadata, only values that adhere to the metadata template schema will be accepted.","externalDocs":{"url":"https://docs.box.com/reference#create-metadata"},"operationId":"createFileMetadata","parameters":[{"in":"path","name":"FILE_ID","required":true,"schema":{"type":"string"}},{"in":"path","name":"SCOPE","required":true,"schema":{"type":"string"}},{"in":"path","name":"TEMPLATE","required":true,"schema":{"type":"string"}}],"requestBody":{"$ref":"#/components/requestBodies/Metadata"},"responses":{"200":{"description":"An instance of the template that includes key:value pairs defined by a user or application.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Metadata"},"examples":{"response":{"value":{"$id":"2094c584-68e1-475c-a581-534a4609594e","$parent":"file_5010739061","$scope":"enterprise_12345","$template":"marketingCollateral","$type":"marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe","$typeVersion":0,"$version":0,"audience1":"internal","author":"Jones","competitiveDocument":"no","currentState":"proposal","documentType":"Q1 plans","status":"active"}}}}}},"409":{"description":"If the template instance already exists