openapi-directory/api/box.com.json

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

{"openapi":"3.0.2","servers":[{"description":"Box Platform API server","url":"https://api.box.com/2.0"}],"info":{"contact":{"email":"devrel@box.com","name":"Box, Inc","url":"https://box.dev","x-twitter":"BoxHQ"},"description":"[Box Platform](https://box.dev) provides functionality to provide access to content stored within [Box](https://box.com). It provides endpoints for basic manipulation of files and folders, management of users within an enterprise, as well as more complex topics such as legal holds and retention policies.","license":{"name":"Apache-2.0","url":"http://www.apache.org/licenses/LICENSE-2.0"},"termsOfService":"https://cloud.app.box.com/s/rmwxu64h1ipr41u49w3bbuvbsa29wku9","title":"Box Platform API","version":"2.0.0","x-apisguru-categories":["cloud"],"x-logo":{"url":"https://twitter.com/BoxHQ/profile_image?size=original"},"x-origin":[{"converter":{"url":"https://github.com/mermade/oas-kit","version":"7.0.4"},"format":"openapi","url":"https://opensource.box.com/box-openapi/openapi.json","version":"3.0"}],"x-providerName":"box.com"},"externalDocs":{"description":"Box Developer Documentation","url":"https://developer.box.com"},"security":[{"OAuth2Security":[]}],"tags":[{"name":"Authorization","x-box-priority":true,"x-box-tag":"authorization"},{"name":"Box Sign","x-box-tag":"sign_requests"},{"name":"Classifications","x-box-tag":"classifications"},{"name":"Classifications on files","x-box-tag":"file_classifications"},{"name":"Classifications on folders","x-box-tag":"folder_classifications"},{"name":"Collaborations","x-box-tag":"user_collaborations"},{"name":"Collaborations (List)","x-box-tag":"list_collaborations"},{"name":"Collections","x-box-tag":"collections"},{"name":"Comments","x-box-tag":"comments"},{"name":"Device pinners","x-box-tag":"device_pinners"},{"name":"Domain restrictions (User exemptions)","x-box-tag":"collaboration_allowlist_exempt_targets"},{"name":"Domain restrictions for collaborations","x-box-tag":"collaboration_allowlist_entries"},{"name":"Downloads","x-box-tag":"downloads"},{"name":"Email aliases","x-box-tag":"email_aliases"},{"name":"Events","x-box-tag":"events"},{"name":"File requests","x-box-tag":"file_requests"},{"name":"File version legal holds","x-box-tag":"file_version_legal_holds"},{"name":"File version retentions","x-box-tag":"file_version_retentions"},{"name":"File versions","x-box-tag":"file_versions"},{"name":"Files","x-box-tag":"files"},{"name":"Folder Locks","x-box-tag":"folder_locks"},{"name":"Folders","x-box-tag":"folders"},{"name":"Group memberships","x-box-tag":"memberships"},{"name":"Groups","x-box-tag":"groups"},{"name":"Invites","x-box-tag":"invites"},{"name":"Legal hold policies","x-box-tag":"legal_hold_policies"},{"name":"Legal hold policy assignments","x-box-tag":"legal_hold_policy_assignments"},{"name":"Metadata cascade policies","x-box-tag":"metadata_cascade_policies"},{"name":"Metadata instances (Files)","x-box-tag":"file_metadata"},{"name":"Metadata instances (Folders)","x-box-tag":"folder_metadata"},{"name":"Metadata templates","x-box-tag":"metadata_templates"},{"name":"Recent items","x-box-tag":"recent_items"},{"name":"Retention policies","x-box-tag":"retention_policies"},{"name":"Retention policy assignments","x-box-tag":"retention_policy_assignments"},{"name":"Search","x-box-tag":"search"},{"name":"Session termination","x-box-tag":"session_termination"},{"name":"Shared links (Files)","x-box-tag":"shared_links_files"},{"name":"Shared links (Folders)","x-box-tag":"shared_links_folders"},{"name":"Shared links (Web Links)","x-box-tag":"shared_links_web_links"},{"name":"Shield information barriers","x-box-tag":"shield_information_barriers"},{"name":"Shield information barrier segments","x-box-tag":"shield_information_barrier_segments"},{"name":"Shield information barrier segment members","x-box-tag":"shield_information_barrier_segment_members"},{"name":"Shield information barrier reports","x-box-tag":"shield_information_barrier_reports"},{"name":"Shield information barrier segment restrictions","x-box-tag":"shield_information_barrier_segment_restrictions"},{"name":"Skills","x-box-tag":"skills"},{"name":"Standard and Zones Storage Policies","x-box-tag":"storage_policies"},{"name":"Standard and Zones Storage Policy Assignments","x-box-tag":"storage_policy_assignments"},{"name":"Task assignments","x-box-tag":"task_assignments"},{"name":"Tasks","x-box-tag":"tasks"},{"name":"Terms of service","x-box-tag":"terms_of_services"},{"name":"Terms of service user statuses","x-box-tag":"terms_of_service_user_statuses"},{"name":"Termination message","x-box-tag":"termination_message"},{"name":"Transfer folders","x-box-tag":"transfer"},{"name":"Trashed files","x-box-tag":"trashed_files"},{"name":"Trashed folders","x-box-tag":"trashed_folders"},{"name":"Trashed items","x-box-tag":"trashed_items"},{"name":"Trashed web links","x-box-tag":"trashed_web_links"},{"name":"Uploads","x-box-tag":"uploads"},{"name":"Uploads (Chunked)","x-box-tag":"chunked_uploads"},{"name":"User avatars","x-box-tag":"avatars"},{"name":"Users","x-box-tag":"users"},{"name":"Watermarks (Files)","x-box-tag":"file_watermarks"},{"name":"Watermarks (Folders)","x-box-tag":"folder_watermarks"},{"name":"Web links","x-box-tag":"web_links"},{"name":"Webhooks","x-box-tag":"webhooks"},{"name":"Workflows","x-box-tag":"workflows"},{"name":"Zip Downloads","x-box-tag":"zip_downloads"}],"paths":{"/authorize":{"get":{"description":"Authorize a user by sending them through the [Box](https://box.com)\nwebsite and request their permission to act on their behalf.\n\nThis is the first step when authenticating a user using\nOAuth 2.0. To request a user's authorization to use the Box APIs\non their behalf you will need to send a user to the URL with this\nformat.","operationId":"get_authorize","parameters":[{"description":"The type of response we'd like to receive.","example":"code","in":"query","name":"response_type","required":true,"schema":{"enum":["code"],"format":"token","type":"string"}},{"description":"The Client ID of the application that is requesting to authenticate\nthe user. To get the Client ID for your application, log in to your\nBox developer console and click the **Edit Application** link for\nthe application you're working with. In the OAuth 2.0 Parameters section\nof the configuration page, find the item labelled `client_id`. The\ntext of that item is your application's Client ID.","example":"ly1nj6n11vionaie65emwzk575hnnmrk","in":"query","name":"client_id","required":true,"schema":{"type":"string"}},{"description":"The URI to which Box redirects the browser after the user has granted\nor denied the application permission. This URI match one of the redirect\nURIs in the configuration of your application. It must be a\nvalid HTTPS URI and it needs to be able to handle the redirection to\ncomplete the next step in the OAuth 2.0 flow.\nAlthough this parameter is optional, it must be a part of the\nauthorization URL if you configured multiple redirect URIs\nfor the application in the developer console. A missing parameter causes\na `redirect_uri_missing` error after the user grants application access.","example":"http://example.com/auth/callback","in":"query","name":"redirect_uri","required":false,"schema":{"format":"url","type":"string"}},{"description":"A custom string of your choice. Box will pass the same string to\nthe redirect URL when authentication is complete. This parameter\ncan be used to identify a user on redirect, as well as protect\nagainst hijacked sessions and other exploits.","example":"my_state","in":"query","name":"state","required":false,"schema":{"type":"string"}},{"description":"A comma-separated list of application scopes you'd like to\nauthenticate the user for. This defaults to all the scopes configured\nfor the application in its configuration page.","example":"admin_readwrite","in":"query","name":"scope","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"text/html":{"schema":{"format":"html","type":"string"}}},"description":"Does not return any data, but rather should be used in the browser."},"default":{"content":{"text/html":{"schema":{"format":"html","type":"string"}}},"description":"Does not return any data, but rather should be used in the browser."}},"security":[],"servers":[{"description":"Server for client-side authentication","url":"https://account.box.com/api/oauth2"}],"summary":"Authorize user","tags":["Authorization"],"x-box-tag":"authorization"}},"/collaboration_whitelist_entries":{"get":{"description":"Returns the list domains that have been deemed safe to create collaborations\nfor within the current enterprise.","operationId":"get_collaboration_whitelist_entries","parameters":[{"description":"Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.","example":"JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii","in":"query","name":"marker","required":false,"schema":{"type":"string"}},{"description":"The maximum number of items to return per page.","example":1000,"in":"query","name":"limit","required":false,"schema":{"format":"int64","maximum":1000,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollaborationAllowlistEntries"}}},"description":"Returns a collection of domains that are allowed for collaboration."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientError"}}},"description":"An unexpected client error."}},"summary":"List allowed collaboration domains","tags":["Domain restrictions for collaborations"],"x-box-tag":"collaboration_allowlist_entries"},"post":{"description":"Creates a new entry in the list of allowed domains to allow\ncollaboration for.","operationId":"post_collaboration_whitelist_entries","requestBody":{"content":{"application/json":{"schema":{"properties":{"direction":{"description":"The direction in which to allow collaborations.","enum":["inbound","outbound","both"],"example":"inbound","type":"string"},"domain":{"description":"The domain to add to the list of allowed domains.","example":"example.com","type":"string"}},"required":["domain","direction"],"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollaborationAllowlistEntry"}}},"description":"Returns a new entry on the list of allowed domains."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientError"}}},"description":"An unexpected client error."}},"summary":"Add domain to list of allowed collaboration domains","tags":["Domain restrictions for collaborations"],"x-box-tag":"collaboration_allowlist_entries"}},"/collaboration_whitelist_entries/{collaboration_whitelist_entry_id}":{"delete":{"description":"Removes a domain from the list of domains that have been deemed safe to create\ncollaborations for within the current enterprise.","operationId":"delete_collaboration_whitelist_entries_id","parameters":[{"description":"The ID of the entry in the list.","example":"213123","in":"path","name":"collaboration_whitelist_entry_id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"A blank response is returned if the entry was\nsuccessfully deleted."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientError"}}},"description":"An unexpected client error."}},"summary":"Remove domain from list of allowed collaboration domains","tags":["Domain restrictions for collaborations"],"x-box-tag":"collaboration_allowlist_entries"},"get":{"description":"Returns a domain that has been deemed safe to create collaborations\nfor within the current enterprise.","operationId":"get_collaboration_whitelist_entries_id","parameters":[{"description":"The ID of the entry in the list.","example":"213123","in":"path","name":"collaboration_whitelist_entry_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollaborationAllowlistEntry"}}},"description":"Returns an entry on the list of allowed domains."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientError"}}},"description":"An unexpected client error."}},"summary":"Get allowed collaboration domain","tags":["Domain restrictions for collaborations"],"x-box-tag":"collaboration_allowlist_entries"}},"/collaboration_whitelist_exempt_targets":{"get":{"description":"Returns a list of users who have been exempt from the collaboration\ndomain restrictions.","operationId":"get_collaboration_whitelist_exempt_targets","parameters":[{"description":"Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.","example":"JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii","in":"query","name":"marker","required":false,"schema":{"type":"string"}},{"description":"The maximum number of items to return per page.","example":1000,"in":"query","name":"limit","required":false,"schema":{"format":"int64","maximum":1000,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollaborationAllowlistExemptTargets"}}},"description":"Returns a collection of user exemptions."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientError"}}},"description":"An unexpected client error."}},"summary":"List users exempt from collaboration domain restrictions","tags":["Domain restrictions (User exemptions)"],"x-box-tag":"collaboration_allowlist_exempt_targets"},"post":{"description":"Exempts a user from the restrictions set out by the allowed list of domains\nfor collaborations.","operationId":"post_collaboration_whitelist_exempt_targets","requestBody":{"content":{"application/json":{"schema":{"properties":{"user":{"description":"The user to exempt.","properties":{"id":{"description":"The ID of the user to exempt.","example":"23522323","type":"string"}},"required":["id"],"type":"object"}},"required":["user"],"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollaborationAllowlistExemptTarget"}}},"description":"Returns a new exemption entry."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientError"}}},"description":"An unexpected client error."}},"summary":"Create user exemption from collaboration domain restrictions","tags":["Domain restrictions (User exemptions)"],"x-box-tag":"collaboration_allowlist_exempt_targets"}},"/collaboration_whitelist_exempt_targets/{collaboration_whitelist_exempt_target_id}":{"delete":{"description":"Removes a user's exemption from the restrictions set out by the allowed list\nof domains for collaborations.","operationId":"delete_collaboration_whitelist_exempt_targets_id","parameters":[{"description":"The ID of the exemption to the list.","example":"984923","in":"path","name":"collaboration_whitelist_exempt_target_id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"A blank response is returned if the exemption was\nsuccessfully deleted."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientError"}}},"description":"An unexpected client error."}},"summary":"Remove user from list of users exempt from domain restrictions","tags":["Domain restrictions (User exemptions)"],"x-box-tag":"collaboration_allowlist_exempt_targets"},"get":{"description":"Returns a users who has been exempt from the collaboration\ndomain restrictions.","operationId":"get_collaboration_whitelist_exempt_targets_id","parameters":[{"description":"The ID of the exemption to the list.","example":"984923","in":"path","name":"collaboration_whitelist_exempt_target_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollaborationAllowlistExemptTarget"}}},"description":"Returns the user's exempted from the list of collaboration domains."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientError"}}},"description":"An unexpected client error."}},"summary":"Get user exempt from collaboration domain restrictions","tags":["Domain restrictions (User exemptions)"],"x-box-tag":"collaboration_allowlist_exempt_targets"}},"/collaborations":{"get":{"description":"Retrieves all pending collaboration invites for this user.","operationId":"get_collaborations","parameters":[{"description":"The status of the collaborations to retrieve","example":"pending","in":"query","name":"status","required":true,"schema":{"enum":["pending"],"type":"string"}},{"description":"A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.","example":["id","type","name"],"explode":false,"in":"query","name":"fields","required":false,"schema":{"items":{"type":"string"},"type":"array"}},{"description":"The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.","example":1000,"in":"query","name":"offset","required":false,"schema":{"default":0,"format":"int64","type":"integer"}},{"description":"The maximum number of items to return per page.","example":1000,"in":"query","name":"limit","required":false,"schema":{"format":"int64","maximum":1000,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collaborations"}}},"description":"Returns a collection of pending collaboration objects.\n\nIf the user has no pending collaborations, the collection\nwill be empty."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientError"}}},"description":"An unexpected client error."}},"summary":"List pending collaborations","tags":["Collaborations (List)"],"x-box-tag":"list_collaborations"},"post":{"description":"Adds a collaboration for a single user or a single group to a file\nor folder.\n\nCollaborations can be created using email address, user IDs, or a\ngroup IDs.\n\nIf a collaboration is being created with a group, access to\nthis endpoint is dependent on the group's ability to be invited.\n\nIf collaboration is in `pending` status, the following fields\nare redacted:\n- `login` and `name` are hidden if a collaboration was created\nusing `user_id`,\n-  `name` is hidden if a collaboration was created using `login`.","operationId":"post_collaborations","parameters":[{"description":"A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.","example":["id","type","name"],"explode":false,"in":"query","name":"fields","required":false,"schema":{"items":{"type":"string"},"type":"array"}},{"description":"Determines if users should receive email notification\nfor the action performed.","example":true,"in":"query","name":"notify","required":false,"schema":{"type":"boolean"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"accessible_by":{"description":"The user or group to give access to the item.","properties":{"id":{"description":"The ID of the user or group.\n\nAlternatively, use `login` to specify a user by email\naddress.","example":"23522323","type":"string"},"login":{"description":"The email address of the user to grant access to the item.\n\nAlternatively, use `id` to specify a user by user ID.","example":"john@example.com","type":"string"},"type":{"description":"The type of collaborator to invite.","enum":["user","group"],"example":"user","type":"string"}},"required":["type"],"type":"object"},"can_view_path":{"description":"Determines if the invited users can see the entire parent path to\nthe associated folder. The user will not gain privileges in any\nparent folder and therefore can not see content the user is not\ncollaborated on.\n\nBe aware that this meaningfully increases the time required to load the\ninvitee's **All Files** page. We recommend you limit the number of\ncollaborations with `can_view_path` enabled to 1,000 per user.\n\nOnly owner or co-owners can invite collaborators with a `can_view_path` of\n`true`.\n\n`can_view_path` can only be used for folder collaborations.","example":true,"type":"boolean"},"expires_at":{"description":"Set the expiration date for the collaboration. At this date, the\ncollaboration will be automatically removed from the item.\n\nThis feature will only work if the **Automatically remove invited\ncollaborators: Allow folder owners to extend the expiry date**\nsetting has been enabled in the **Enterprise Settings**\nof the **Admin Console**. When the setting is not enabled,\ncollaborations can not have an expiry date and a value for this\nfield will be result in an error.","example":"2025-06-15T13:49:19.949Z","format":"date-time","type":"string"},"item":{"description":"The item to attach the comment to.","properties":{"id":{"description":"The ID of the item that will be granted access to","example":"11446498","type":"string"},"type":{"description":"The type of the item that this collaboration will be\ngranted access to","enum":["file","folder"],"example":"file","type":"string"}},"required":["id","type"],"type":"object"},"role":{"description":"The level of access granted.","enum":["editor","viewer","previewer","uploader","previewer uploader","viewer uploader","co-owner"],"example":"editor","type":"string"}},"required":["item","accessible_by","role"],"type":"object"}}}},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collaboration"}}},"description":"Returns a new collaboration object."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientError"}}},"description":"Returns an error when the user does not have the\nright permissions to create the collaboration.\n\n* `forbidden_by_policy`: Creating a\ncollaboration is forbidden due to information\nbarrier restrictions."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientError"}}},"description":"An unexpected client error."}},"summary":"Create collaboration","tags":["Collaborations"],"x-box-tag":"user_collaborations"}},"/collaborations/{collaboration_id}":{"delete":{"description":"Deletes a single collaboration.","operationId":"delete_collaborations_id","parameters":[{"description":"The ID of the collaboration","example":"1234","in":"path","name":"collaboration_id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"A blank response is returned if the collaboration was\nsuccessfully deleted."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientError"}}},"description":"An unexpected client error."}},"summary":"Remove collaboration","tags":["Collaborations"],"x-box-tag":"user_collaborations"},"get":{"description":"Retrieves a single collaboration.","operationId":"get_collaborations_id","parameters":[{"description":"The ID of the collaboration","example":"1234","in":"path","name":"collaboration_id","required":true,"schema":{"type":"string"}},{"description":"A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.","example":["id","type","name"],"explode":false,"in":"query","name":"fields","required":false,"schema":{"items":{"type":"string"},"type":"array"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collaboration"}}},"description":"Returns a collaboration object."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientError"}}},"description":"An unexpected client error."}},"summary":"Get collaboration","tags":["Collaborations"],"x-box-tag":"user_collaborations"},"put":{"description":"Updates a collaboration.\nCan be used to change the owner of an item, or to\naccept collaboration invites.","operationId":"put_collaborations_id","parameters":[{"description":"The ID of the collaboration","example":"1234","in":"path","name":"collaboration_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"can_view_path":{"description":"Determines if the invited users can see the entire parent path to\nthe associated folder. The user will not gain privileges in any\nparent folder and therefore can not see content the user is not\ncollaborated on.\n\nBe aware that this meaningfully increases the time required to load the\ninvitee's **All Files** page. We recommend you limit the number of\ncollaborations with `can_view_path` enabled to 1,000 per user.\n\nOnly owner or co-owners can invite collaborators with a `can_view_path` of\n`true`.\n\n`can_view_path` can only be used for folder collaborations.","example":true,"type":"boolean"},"expires_at":{"description":"Update the expiration date for the collaboration. At this date,\nthe collaboration will be automatically removed from the item.\n\nThis feature will only work if the **Automatically remove invited\ncollaborators: Allow folder owners to extend the expiry date**\nsetting has been enabled in the **Enterprise Settings**\nof the **Admin Console**. When the setting is not enabled,\ncollaborations can not have an expiry date and a value for this\nfield will be result in an error.\n\nAdditionally, a collaboration can only be given an\nexpiration if it was created after the **Automatically remove\ninvited collaborator** setting was enabled.","example":"2025-06-15T13:49:19.950Z","format":"date-time","type":"string"},"role":{"description":"The level of access granted.","enum":["editor","viewer","previewer","uploader","previewer uploader","viewer uploader","co-owner","owner"],"example":"editor","type":"string"},"status":{"description":"<!--alex ignore reject-->\nSet the status of a `pending` collaboration invitation,\neffectively accepting, or rejecting the invite.","enum":["pending","accepted","rejected"],"example":"accepted","type":"string"}},"required":["role"],"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collaboration"}}},"description":"Returns an updated collaboration object unless the owner has changed."},"204":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collaboration"}}},"description":"If the role is changed to `owner`, the collaboration is deleted\nand a new collaboration is created. The previous `owner` of\nthe old collaboration will be a `co-owner` on the new collaboration."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientError"}}},"description":"Returns an error if the authenticated user does not have the right\npermissions to update the collaboration.\n\nAdditionally, this error may occur when attempting to update the\n`expires_at` field for the collaboration without the **Automatically\nremove invited collaborators: Allow folder owners to extend the expiry\ndate** setting enabled in the admin dashboard of the enterprise."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientError"}}},"description":"An unexpected client error."}},"summary":"Update collaboration","tags":["Collaborations"],"x-box-tag":"user_collaborations"}},"/collections":{"get":{"description":"Retrieves all collections for a given user.\n\nCurrently, only the `favorites` collection\nis supported.","operationId":"get_collections","parameters":[{"description":"A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.","example":["id","type","name"],"explode":false,"in":"query","name":"fields","required":false,"schema":{"items":{"type":"string"},"type":"array"}},{"description":"The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.","example":1000,"in":"query","name":"offset","required":false,"schema":{"default":0,"format":"int64","type":"integer"}},{"description":"The maximum number of items to return per page.","example":1000,"in":"query","name":"limit","required":false,"schema":{"format":"int64","maximum":1000,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collections"}}},"description":"Returns all collections for the given user"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientError"}}},"description":"An unexpected client error."}},"summary":"List all collections","tags":["Collections"],"x-box-tag":"collections"}},"/collections/{collection_id}/items":{"get":{"description":"Retrieves the files and/or folders contained within\nthis collection.","operationId":"get_collections_id_items","parameters":[{"description":"The ID of the collection.","example":"926489","in":"path","name":"collection_id","required":true,"schema":{"type":"string"}},{"description":"A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.","example":["id","type","name"],"explode":false,"in":"query","name":"fields","required":false,"schema":{"items":{"type":"string"},"type":"array"}},{"description":"The offset of the item at which to begin the response.\n\nQueries with offset parameter value\nexceeding 10000 will be rejected\nwith a 400 response.","example":1000,"in":"query","name":"offset","required":false,"schema":{"default":0,"format":"int64","type":"integer"}},{"description":"The maximum number of items to return per page.","example":1000,"in":"query","name":"limit","required":false,"schema":{"format":"int64","maximum":1000,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Items"}}},"description":"Returns an array of items in the collection."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientError"}}},"description":"An unexpected client error."}},"summary":"List collection items","tags":["Collections"],"x-box-tag":"collections"}},"/comments":{"post":{"description":"Adds a comment by the user to a specific file, or\nas a reply to an other comment.","operationId":"post_comments","parameters":[{"description":"A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.","example":["id","type","name"],"explode":false,"in":"query","name":"fields","required":false,"schema":{"items":{"type":"string"},"type":"array"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"item":{"description":"The item to attach the comment to.","properties":{"id":{"description":"The ID of the item","example":"11446498","type":"string"},"type":{"description":"The type of the item that this comment will be placed on.","enum":["file","comment"],"example":"file","type":"string"}},"required":["id","type"],"type":"object"},"message":{"description":"The text of the comment.\n\nTo mention a user, use the `tagged_message`\nparameter instead.","example":"Review completed!","type":"string"},"tagged_message":{"description":"The text of the comment, including `@[user_id:name]`\nsomewhere in the message to mention another user, which\nwill send them an email notification, letting them know\nthey have been mentioned.\n\nThe `user_id` is the target user's ID, where the `name`\ncan be any custom phrase. In the Box UI this name will\nlink to the user's profile.\n\nIf you are not mentioning another user, use `message`\ninstead.","example":"@[1234:John] Review completed!","type":"string"}},"required":["message"],"type":"object"}}}},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Comment"}}},"description":"Returns the newly created comment object.\n\nNot all available fields are returned by default. Use the\n[fields](#param-fields) query parameter to explicitly request\nany specific fields."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientError"}}},"description":"An unexpected client error."}},"summary":"Create comment","tags":["Comments"],"x-box-tag":"comments"}},"/comments/{comment_id}":{"delete":{"description":"Permanently deletes a comment.","operationId":"delete_comments_id","parameters":[{"description":"The ID of the comment.","example":"12345","in":"path","name":"comment_id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Returns an empty response when the comment has been deleted."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientError"}}},"description":"An unexpected client error."}},"summary":"Remove comment","tags":["Comments"],"x-box-tag":"comments"},"get":{"description":"Retrieves the message and metadata for a specific comment, as well\nas information on the user who created the comment.","operationId":"get_comments_id","parameters":[{"description":"The ID of the comment.","example":"12345","in":"path","name":"comment_id","required":true,"schema":{"type":"string"}},{"description":"A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.","example":["id","type","name"],"explode":false,"in":"query","name":"fields","required":false,"schema":{"items":{"type":"string"},"type":"array"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Comment--Full"}}},"description":"Returns a full comment object."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientError"}}},"description":"An unexpected client error."}},"summary":"Get comment","tags":["Comments"],"x-box-tag":"comments"},"put":{"description":"Update the message of a comment.","operationId":"put_comments_id","parameters":[{"description":"The ID of the comment.","example":"12345","in":"path","name":"comment_id","required":true,"schema":{"type":"string"}},{"description":"A comma-separated list of attributes to include in the\nresponse. This can be used to request fields that are\nnot normally returned in a standard response.\n\nBe aware that specifying this parameter will have the\neffect that none of the standard fields are returned in\nthe response unless explicitly specified, instead only\nfields for the mini representation are returned, additional\nto the fields requested.","example":["id","type","name"],"explode":false,"in":"query","name":"fields","required":false,"schema":{"items":{"type":"string"},"type":"array"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"message":{"description":"The text of the comment to update","example":"Review completed!","type":"string"}},"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Comment--Full"}}},"description":"Returns the updated comment object."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientError"}}},"description":"An unexpected client error."}},"summary":"Update comment","tags":["Comments"],"x-box-tag":"comments"}},"/device_pinners/{device_pinner_id}":{"delete":{"description":"Deletes an individual device pin.","operationId":"delete_device_pinners_id","parameters":[{"description":"The ID of the device pin","example":"2324234","in":"path","name":"device_pinner_id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Returns an empty response when the pin has been deleted."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientError"}}},"description":"An unexpected client error."}},"summary":"Remove device pin","tags":["Device pinners"],"x-box-tag":"device_pinners"},"get":{"description":"Retrieves information about an individual device pin.","operationId":"get_device_pinners_id","parameters":[{"description":"The ID of the device pin","example":"2324234","in":"path","name":"device_pinner_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DevicePinner"}}},"description":"Returns information about a single device pin."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientError"}}},"description":"An unexpected client error."}},"summary":"Get device pin","tags":["Device pinners"],"x-box-tag":"device_pinners"}},"/enterprises/{enterprise_id}/device_pinners":{"get":{"description":"Retrieves all the device pins within an enterprise.\n\nThe user must have admin privileges, and the application\nneeds the \"manage enterprise\" scope to make this call.","operationId":"get_enterprises_id_device_pinners","parameters":[{"description":"The ID of the enterprise","example":"3442311","in":"path","name":"enterprise_id","required":true,"schema":{"type":"string"}},{"description":"Defines the position marker at which to begin returning results. This is\nused when paginating using marker-based pagination.\n\nThis requires `usemarker` to be set to `true`.","example":"JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii","in":"query","name":"marker","required":false,"schema":{"type":"string"}},{"description":"The maximum number of items to return per page.","example":1000,"in":"query","name":"limit","required":false,"schema":{"format":"int64","maximum":1000,"type":"integer"}},{"description":"The direction to sort results in. This can be either in alphabetical ascending\n(`ASC`) or descending (`DESC`) order.","example":"ASC","in":"query","name":"direction","required":false,"schema":{"enum":["ASC","DESC"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DevicePinners"}}},"description":"Returns a list of device pins for a given enterprise."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientError"}}},"description":"An unexpected client error."}},"summary":"List enterprise device pins","tags":["Device pinners"],"x-box-tag":"device_pinners"}},"/events":{"get":{"description":"Returns up to a year of past events for a given user\nor for the entire enterprise.\n\nBy default this returns events for the authenticated user. To retrieve events\nfor the entire enterprise, set the `stream_type` to `admin_logs_streaming`\nfor live monitoring of new events, or `admin_logs` for querying across\nhistorical events. The user making the API call will\nneed to have admin privileges, and the application will need to have the\nscope `manage enterprise properties` checked.","operationId":"get_events","parameters":[{"description":"Defines the type of events that are returned\n\n* `all` returns everything for a user and is the default\n* `changes` returns events that may cause file tree changes\n  such as file updates or collaborations.\n* `sync` is similar to `changes` but only applies to synced folders\n* `admin_logs` returns all events for an entire enterprise and\n  requires the user making the API call to have admin permissions. This\n  stream type is for programmatically pulling from a 1 year history of\n  events across all users within the enterprise and within a\n  `created_after` and `created_before` time frame. The complete history\n  of events will be returned in chronological order based on the event\n  time, but latency will be much higher than `admin_logs_streaming`.\n* `admin_logs_streaming` returns all events for an entire enterprise and\n  requires the user making the API call to have admin permissions. This\n  stream type is for polling for recent events across all users within\n  the enterprise. Latency will be much lower than `admin_logs`, but\n  events will not be returned in chronological order and may\n  contain duplicates.","example":"all","in":"query","name":"stream_type","schema":{"default":"all","enum":["all","changes","sync","admin_logs","admin_logs_streaming"],"type":"string"}},{"description":"The location in the event stream to start receiving events from.\n\n* `now` will return an empty list events and\nthe latest stream position for initialization.\n* `0` or `null` will return all events.","example":"1348790499819","in":"query","name":"stream_position","schema":{"type":"string"}},{"description":"Limits the number of events returned\n\nNote: Sometimes, the events less than the limit requested can be returned\neven when there may be more events remaining. This is primarily done in\nthe case where a number of events have already been retrieved and these\nretrieved events are returned rather than delaying for an unknown amount\nof time to see if there are any more results.","example":50,"in":"query","name":"limit","schema":{"default":100,"format":"int64","maximum":500,"type":"integer"}},{"description":"A comma-separated list of events to filter by. This can only be used when\nrequesting the events with a `stream_type` of `admin_logs` or\n`adming_logs_streaming`. For any other `stream_type` this value will be\nignored.","example":["ACCESS_GRANTED"],"explode":false,"in":"query","name":"event_type","schema":{"items":{"description":"An event type that can be filtered by","enum":["ACCESS_GRANTED","ACCESS_REVOKED","ADD_DEVICE_ASSOCIATION","ADD_LOGIN_ACTIVITY_DEVICE","ADMIN_LOGIN","APPLICATION_CREATED","APPLICATION_PUBLIC_KEY_ADDED","APPLICATION_PUBLIC_KEY_DELETED","CHANGE_ADMIN_ROLE","CHANGE_FOLDER_PERMISSION","COLLABORATION_ACCEPT","COLLABORATION_EXPIRATION","COLLABORATION_INVITE","COLLABORATION_REMOVE","COLLABORATION_ROLE_CHANGE","COMMENT_CREATE","COMMENT_DELETE","CONTENT_WORKFLOW_ABNORMAL_DOWNLOAD_ACTIVITY","CONTENT_WORKFLOW_AUTOMATION_ADD","CONTENT_WORKFLOW_AUTOMATION_DELETE","CONTENT_WORKFLOW_POLICY_ADD","CONTENT_WORKFLOW_SHARING_POLICY_VIOLATION","CONTENT_WORKFLOW_UPLOAD_POLICY_VIOLATION","COPY","DATA_RETENTION_CREATE_RETENTION","DATA_RETENTION_REMOVE_RETENTION","DELETE","DELETE_USER","DEVICE_TRUST_CHECK_FAILED","DOWNLOAD","EDIT","EDIT_USER","EMAIL_ALIAS_CONFIRM","EMAIL_ALIAS_REMOVE","ENTERPRISE_APP_AUTHORIZATION_UPDATE","EXTERNAL_COLLAB_SECURITY_SETTINGS","FAILED_LOGIN","FILE_MARKED_MALICIOUS","FILE_WATERMARKED_DOWNLOAD","GROUP_ADD_ITEM","GROUP_ADD_USER","GROUP_CREATION","GROUP_DELETION","GROUP_EDITED","GROUP_REMOVE_ITEM","GROUP_REMOVE_USER","ITEM_MODIFY","ITEM_OPEN","ITEM_SHARED_UPDATE","ITEM_SYNC","ITEM_UNSYNC","LEGAL_HOLD_ASSIGNMENT_CREATE","LEGAL_HOLD_ASSIGNMENT_DELETE","LEGAL_HOLD_POLICY_CREATE","LEGAL_HOLD_POLICY_DELETE","LEGAL_HOLD_POLICY_UPDATE","LOCK","LOGIN","METADATA_INSTANCE_CREATE","METADATA_INSTANCE_DELETE","METADATA_INSTANCE_UPDATE","METADATA_TEMPLATE_CREATE","METADATA_TEMPLATE_DELETE","METADATA_TEMPLATE_UPDATE","MOVE","NEW_USER","OAUTH2_ACCESS_TOKEN_REVOKE","PREVIEW","REMOVE_DEVICE_ASSOCIATION","REMOVE_LOGIN_ACTIVITY_DEVICE","RENAME","RETENTION_POLICY_ASSIGNMENT_ADD","SHARE","SHARE_EXPIRATION","SHIELD_ALERT","SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED","SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED_MISSING_JUSTIFICATION","SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED","SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED_MISSING_JUSTIFICATION","SHIELD_JUSTIFICATION_APPROVAL","SIGN_DOCUMENT_ASSIGNED","SIGN_DOCUMENT_CANCELLED","SIGN_DOCUMENT_COMPLETED","SIGN_DOCUMENT_CONVERTED","SIGN_DOCUMENT_CREATED","SIGN_DOCUMENT_DECLINED","SIGN_DOCUMENT_EXPIRED","SIGN_DOCUMENT_SIGNED","SIGN_DOCUMENT_VIEWED_BY_SIGNED","SIGNER_DOWNLOADED","SIGNER_FORWARDED","STORAGE_EXPIRATION","TASK_ASSIGNMENT_CREATE","TASK_ASSIGNMENT_DELETE","TASK_ASSIGNMENT_UPDATE","TASK_CREATE","TASK_UPDATE","TERMS_OF_SERVICE_ACCEPT","TERMS_OF_SERVICE_REJECT","UNDELETE","UNLOCK","UNSHARE","UPDATE_COLLABORATION_EXPIRATION","UPDATE_SHARE_EXPIRATION","UPLOAD","USER_AUTHENTICATE_OAUTH2_ACCESS_TOKEN_CREATE","WATERMARK_LABEL_CREATE","WATERMARK_LABEL_DELETE"],"type":"string"},"type":"array"}},{"description":"The lower bound date and time to return events for. This can only be used\nwhen requesting the events with a `stream_type` of `admin_logs`. For any\nother `stream_type` this value will be ignored.","example":"2025-06-15T13:49:19.950Z","in":"query","name":"created_after","schema":{"format":"date-time","type":"string"}},{"description":"The upper bound date and time to return events for. This can only be used\nwhen requesting the events with a `stream_type` of `admin_logs`. For any\nother `stream_type` this value will be ignored.","example":"2025-06-15T13:49:19.950Z","in":"query","name":"created_before","required":false,"schema":{"format":"date-time","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Events"}}},"description":"Returns a list of event objects.\n\nEvents objects are returned in pages, with each page (chunk)\nincluding a list of event objects. The response includes a\n`chunk_size` parameter indicating how many events were returned in this\nchunk, as well as the next `stream_position` that can be\nqueried."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientError"}}},"description":"An unexpected client error."}},"summary":"List user and enterprise events","tags":["Events"],"x-box-tag":"events"},"options":{"description":"Returns a list of real-time servers that can be used for long-polling updates\nto the [event stream](#get-events).\n\nLong polling is the concept where a HTTP request is kept open until the\nserver sends a response, then repeating the process over and over to receive\nupdated responses.\n\nLong polling the event stream can only be used for user events, not for\nenterprise events.\n\nTo use long polling, first use this endpoint to retrieve a list of long poll\nURLs. Next, make a long poll request to any of the provided URLs.\n\nWhen an event occurs in monitored account a response with the value\n`new_change` will be sent. The response contains no other details as\nit only serves as a prompt to take further action such as sending a\nrequest to the [events endpoint](#get-events) with the last known\n`stream_position`.\n\nAfter the server sends this response it closes the connection. You must now\nrepeat the long poll process to begin listening for events again.\n\nIf no events occur for a while and the connection times out you will\nreceive a response with the value `reconnect`. When you receive this response\nyou’ll make another call to this endpoint to restart the process.\n\nIf you receive no events in `retry_timeout` seconds then you will need to\nmake another request to the real-time server (one of the URLs in the response\nfor this endpoint). This might be necessary due to network errors.\n\nFinally, if you receive a `max_retries` error when making a request to the\nreal-time server, you should start over by making a call to this endpoint\nfirst.","operationId":"options_events","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RealtimeServers"}}},"description":"Returns a paginated array of servers that can be used\ninstead of the regular endpoints for long-polling events."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientError"}}},"description":"An unexpected client error."}},"summary":"Get events long poll endpoint","tags":["Events"],"x-box-tag":"events"}},"/file_requests/{file_request_id}":{"delete":{"description":"Deletes a file request permanently.","operationId":"delete_file_requests_id","parameters":[{"description":"The unique identifier that represent a file request.\n\nThe ID for any file request can be determined\nby visiting a file request builder in the web application\nand copying the ID from the URL. For example,\nfor the URL `https://*.app.box.com/filerequest/123`\nthe `file_request_id` is `123`.","example":"123","in":"path","name":"file_request_id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"descript