Cloud Storage & File Sharing — entry 001 of 18
Box
Box is an enterprise content-management platform offering secure file storage, sharing, and collaboration, with a REST API and SDKs for building custom document workflows. A live GET against the real gateway, api.box.com/2.0/users/me, returned a 401 without a token, reconfirming OAuth 2.0 bearer auth over HTTPS, and a follow-up OPTIONS preflight returned Access-Control-Allow-Origin: *, resolving cors from unknown to yes. Personal accounts get 10GB free, while paid Business and Enterprise plans (plus metered Box Platform usage) unlock larger storage and API-driven workflows.
AuthenticationOAuthRequires an OAuth flow; expect app registration.
HTTPSSupportedTraffic is encrypted in transit.
CORSEnabledCallable directly from browser JavaScript.
PricingFreemiumA usable free tier exists, with paid plans for more volume.
FormatsJSONResponses can be requested as JSON.
GreatAPIs Score
Score74
Authentication8/25OAuth flow required
Pricing17/20Freemium tier available
Docs20/20Machine-readable spec file bundled
Formats9/15Single response format
Freshness20/20Verified within 6 months
Embed this badge
<a href="https://greatapis.com/api/box/"><img src="https://greatapis.com/badge/box.svg" alt="Scored 74 on greatapis.com"></a>Auth quickstart
- Register an app / run the OAuth flow to obtain a bearer token.
- Send it as an Authorization header
Authorization: Bearer <token>
Stored keyNo key stored
Your key is stored only in this browser (localStorage) and sent directly to the API — never to greatapis.
Endpoints
AI5
A set of endpoints used to interact with supported LLMs.
POST/ai/askAsk question
Request body
application/json — AiAsk
Responses
| Status | Description | Schema |
|---|---|---|
200 | A successful response including the answer from the LLM. | AiResponse--Full |
204 | No content is available to answer the question. This is returned when the request item is a hub, but content in the hubs is not indexed. To ensure content in the hub is indexed, make sure Box AI for Hubs in the Admin Console was enabled before hub creation. | — |
500 | An unexpected server error. | ClientError |
default | An unexpected error. | ClientError |
POST/ai/extractExtract metadata (freeform)
Request body
application/json — AiExtract
Responses
| Status | Description | Schema |
|---|---|---|
200 | A response including the answer from the LLM. | AiResponse |
500 | An unexpected server error. | ClientError |
default | An unexpected error. | ClientError |
POST/ai/extract_structuredExtract metadata (structured)
Request body
application/json — AiExtractStructured
Responses
| Status | Description | Schema |
|---|---|---|
200 | A successful response including the answer from the LLM. | AiExtractStructuredResponse |
500 | An unexpected server error. | ClientError |
default | An unexpected error. | ClientError |
POST/ai/text_genGenerate text
Request body
application/json — AiTextGen
Responses
| Status | Description | Schema |
|---|---|---|
200 | A successful response including the answer from the LLM. | AiResponse |
500 | An unexpected server error. | ClientError |
default | An unexpected error. | ClientError |
GET/ai_agent_defaultGet AI agent default configuration
Parameters
| Name | In | Required | Type |
|---|---|---|---|
mode | query | yes | string |
language | query | no | string |
model | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | A successful response including the default agent configuration. This response can be one of the following four objects: * AI agent for questions * AI agent for text generation * AI agent for freeform metadata extraction * AI agent for structured metadata extraction. The response depends on the agent configuration requested in this endpoint. | AiAgent |
500 | An unexpected server error. | ClientError |
default | An unexpected error. | ClientError |
AI Studio5
A set of endpoints used to interact with AI Studio.
GET/ai_agentsList AI agents
Parameters
| Name | In | Required | Type |
|---|---|---|---|
mode | query | no | array |
fields | query | no | array |
agent_state | query | no | array |
include_box_default | query | no | boolean |
marker | query | no | string |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | A successful response including the agents list. | AiMultipleAgentResponse |
400 | An unexpected client error. | ClientError |
500 | An unexpected server error. | ClientError |
POST/ai_agentsCreate AI agent
Request body
application/json — CreateAiAgent
Responses
| Status | Description | Schema |
|---|---|---|
200 | Definition of created AI agent. | AiSingleAgentResponse--Full |
400 | An unexpected client error. | ClientError |
500 | An unexpected server error. | ClientError |
GET/ai_agents/{agent_id}Get AI agent by agent ID
Parameters
| Name | In | Required | Type |
|---|---|---|---|
agent_id | path | yes | string |
fields | query | no | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | A successful response including the agent. | AiSingleAgentResponse--Full |
400 | An unexpected client error. | ClientError |
500 | An unexpected server error. | ClientError |
PUT/ai_agents/{agent_id}Update AI agent
Parameters
| Name | In | Required | Type |
|---|---|---|---|
agent_id | path | yes | string |
Request body
application/json — CreateAiAgent
Responses
| Status | Description | Schema |
|---|---|---|
200 | Definition of created AI agent. | AiSingleAgentResponse--Full |
400 | An unexpected client error. | ClientError |
500 | An unexpected server error. | ClientError |
DELETE/ai_agents/{agent_id}Delete AI agent
Parameters
| Name | In | Required | Type |
|---|---|---|---|
agent_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | A successful response with no content. | — |
400 | An unexpected client error. | ClientError |
404 | Returned if the AI agent is not found. | ClientError |
500 | An unexpected server error. | ClientError |
App item associations2
GET/files/{file_id}/app_item_associationsList file app item associations
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
limit | query | no | integer |
marker | query | no | string |
application_type | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a collection of app item objects. If there are no app items on this file, an empty collection will be returned. This list includes app items on ancestors of this File. | AppItemAssociations |
404 | Returned if the file is not found, or the user does not have access to the file. | ClientError |
default | An unexpected client error. | ClientError |
GET/folders/{folder_id}/app_item_associationsList folder app item associations
Parameters
| Name | In | Required | Type |
|---|---|---|---|
folder_id | path | yes | string |
limit | query | no | integer |
marker | query | no | string |
application_type | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a collection of app item objects. If there are no app items on this folder an empty collection will be returned. This list includes app items on ancestors of this folder. | AppItemAssociations |
404 | Returned if the folder is not found, or the user does not have access to the folder. | ClientError |
default | An unexpected client error. | ClientError |
Authorization4
A set of endpoints used to manage user authorization process.
GET/authorizeAuthorize user
Parameters
| Name | In | Required | Type |
|---|---|---|---|
response_type | query | yes | string |
client_id | query | yes | string |
redirect_uri | query | no | string |
state | query | no | string |
scope | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Does not return any data, but rather should be used in the browser. | — |
default | Does not return any data, but rather should be used in the browser. | — |
POST/oauth2/revokeRevoke access token
Request body
application/x-www-form-urlencoded — PostOAuth2Revoke
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns an empty response when the token was successfully revoked. | — |
400 | An authentication error. | OAuth2Error |
default | An authentication error. | OAuth2Error |
POST/oauth2/tokenRequest access token
Request body
application/x-www-form-urlencoded — PostOAuth2Token
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a new Access Token that can be used to make authenticated API calls by passing along the token in a authorization header as follows `Authorization: Bearer <Token>`. | AccessToken |
400 | An authentication error. | OAuth2Error |
default | An authentication error. | OAuth2Error |
POST/oauth2/token#refreshRefresh access token
Request body
application/x-www-form-urlencoded — PostOAuth2Token--RefreshAccessToken
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a new Access Token that can be used to make authenticated API calls by passing along the token in a authorization header as follows `Authorization: Bearer <Token>`. | AccessToken |
400 | An authentication error. | OAuth2Error |
default | An authentication error. | OAuth2Error |
Box Sign requests5
Box Sign requests are used to submit a file for signature.
GET/sign_requestsList Box Sign requests
Parameters
| Name | In | Required | Type |
|---|---|---|---|
marker | query | no | string |
limit | query | no | integer |
senders | query | no | array |
shared_requests | query | no | boolean |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a collection of sign requests. | SignRequests |
default | An unexpected client error. | ClientError |
POST/sign_requestsCreate Box Sign request
Request body
application/json — SignRequestCreateRequest
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns a Box Sign request object. | SignRequest |
default | An unexpected client error. | ClientError |
GET/sign_requests/{sign_request_id}Get Box Sign request by ID
Parameters
| Name | In | Required | Type |
|---|---|---|---|
sign_request_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a signature request. | SignRequest |
404 | Returns an error when the signature request cannot be found, the user does not have access to the signature request, or `sign_files` and/or `parent_folder` is deleted. | ClientError |
default | An unexpected client error. | ClientError |
POST/sign_requests/{sign_request_id}/cancelCancel Box Sign request
Parameters
| Name | In | Required | Type |
|---|---|---|---|
sign_request_id | path | yes | string |
Request body
application/json — SignRequestCancelRequest
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a Sign Request object. | SignRequest |
404 | Returns an error when the sign request cannot be found or the user does not have access to the sign request. | ClientError |
default | An unexpected client error. | ClientError |
POST/sign_requests/{sign_request_id}/resendResend Box Sign request
Parameters
| Name | In | Required | Type |
|---|---|---|---|
sign_request_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
202 | Returns an empty response when the API call was successful. The email notifications will be sent asynchronously. | — |
404 | Returns an error when the signature request cannot be found or the user does not have access to the signature request. | ClientError |
default | An unexpected client error. | ClientError |
Classifications4
Classification labels are used for content that is sensitive or under security restrictions.
GET/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schemaList all classifications
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. | ClassificationTemplate |
400 | Returned if any of the request parameters are not valid. | ClientError |
404 | Returned when a template name is not correct. Please make sure the URL for the request is correct. | ClientError |
default | An unexpected client error. | ClientError |
PUT/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema#addAdd classification
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the updated `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. | ClassificationTemplate |
400 | Returned if any of the request parameters are not valid. | ClientError |
404 | Returned when a template name is not correct. Please make sure the URL for the request is correct. | ClientError |
default | An unexpected client error. | ClientError |
PUT/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema#updateUpdate classification
Request body
application/json-patch+json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the updated `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. | ClassificationTemplate |
400 | Returned if any of the request parameters are not valid. | ClientError |
404 | Returned when a template name is not correct. Please make sure the URL for the request is correct. | ClientError |
default | An unexpected client error. | ClientError |
POST/metadata_templates/schema#classificationsAdd initial classifications
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a new `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. | ClassificationTemplate |
400 | Returned if any of the request parameters are not valid. | ClientError |
404 | Returned when a template name is not correct. Please make sure the URL for the request is correct. | ClientError |
default | An unexpected client error. | ClientError |
Classifications on files4
Classification labels are used for files that are sensitive or under security restrictions.
GET/files/{file_id}/metadata/enterprise/securityClassification-6VMVochwUWoGet classification on file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns an instance of the `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. | Classification |
403 | Returned when the request parameters are not valid. | ClientError |
404 | Returned if the metadata template specified was not applied to this file or the user does not have access to the file. * `instance_not_found` - The metadata template was not applied to the file. | ClientError |
405 | Returned when the method was not allowed. | ClientError |
default | An unexpected client error. | ClientError |
POST/files/{file_id}/metadata/enterprise/securityClassification-6VMVochwUWoAdd classification to file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns the classification template instance that was applied to the file. | Classification |
400 | Returns an error when the request body is not valid. * `schema_validation_failed` - The request body contains a value for a field that either does not exist, or for which the value or type does not match the expected field type. An example might be an unknown option for an `enum` or `multiSelect` field. | ClientError |
404 | Returns an error when the file or metadata template was not found. * `not_found` - The file could not be found, or the user does not have access to the file. * `instance_tuple_not_found` - The metadata template was not found. | ClientError |
409 | Returns an error when an instance of this metadata template is already present on the file. * `tuple_already_exists` - An instance of them metadata template already exists on the file. | ClientError |
default | An unexpected client error. | ClientError |
PUT/files/{file_id}/metadata/enterprise/securityClassification-6VMVochwUWoUpdate classification on file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
Request body
application/json-patch+json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the updated classification metadata template instance. | Classification |
400 | Returns an error when the request body is not valid. * `bad_request` - The request body format is not an array of valid JSON Patch operations. | ClientError |
500 | Returns an error in some edge cases when the request body is not a valid array of JSON Patch items. | ClientError |
default | An unexpected client error. | ClientError |
DELETE/files/{file_id}/metadata/enterprise/securityClassification-6VMVochwUWoRemove classification from file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Returns an empty response when the classification is successfully deleted. | — |
400 | Returned when the request parameters are not valid. | ClientError |
404 | Returns an error when the file does not have any classification applied to it, or when the user does not have access to the file. * `instance_not_found` - An instance of the classification metadata template with the was not found on this file. * `not_found` - The file was not found, or the user does not have access to the file. | ClientError |
405 | Returned when the method was not allowed. | ClientError |
default | An unexpected client error. | ClientError |
Classifications on folders4
Classification labels are used for folders that are sensitive or under security restrictions.
GET/folders/{folder_id}/metadata/enterprise/securityClassification-6VMVochwUWoGet classification on folder
Parameters
| Name | In | Required | Type |
|---|---|---|---|
folder_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns an instance of the `securityClassification` metadata template, which contains a `Box__Security__Classification__Key` field that lists all the classifications available to this enterprise. | Classification |
403 | Returned when the request parameters are not valid. | ClientError |
404 | Returned if the metadata template specified was not applied to this folder or the user does not have access to the folder. * `instance_not_found` - The metadata template was not applied to the folder. | ClientError |
405 | Returned when the method was not allowed. | ClientError |
default | An unexpected client error. | ClientError |
POST/folders/{folder_id}/metadata/enterprise/securityClassification-6VMVochwUWoAdd classification to folder
Parameters
| Name | In | Required | Type |
|---|---|---|---|
folder_id | path | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns the classification template instance that was applied to the folder. | Classification |
400 | Returns an error when the request body is not valid. * `schema_validation_failed` - The request body contains a value for a field that either does not exist, or for which the value or type does not match the expected field type. An example might be an unknown option for an `enum` or `multiSelect` field. | ClientError |
404 | Returns an error when the folder or metadata template was not found. * `not_found` - The folder could not be found, or the user does not have access to the folder. * `instance_tuple_not_found` - The metadata template was not found. | ClientError |
409 | Returns an error when an instance of this metadata template is already present on the folder. * `tuple_already_exists` - An instance of them metadata template already exists on the folder. | ClientError |
default | An unexpected client error. | ClientError |
PUT/folders/{folder_id}/metadata/enterprise/securityClassification-6VMVochwUWoUpdate classification on folder
Parameters
| Name | In | Required | Type |
|---|---|---|---|
folder_id | path | yes | string |
Request body
application/json-patch+json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the updated classification metadata template instance. | Classification |
400 | Returns an error when the request body is not valid. * `bad_request` - The request body format is not an array of valid JSON Patch operations. | ClientError |
500 | Returns an error in some edge cases when the request body is not a valid array of JSON Patch items. | ClientError |
default | An unexpected client error. | ClientError |
DELETE/folders/{folder_id}/metadata/enterprise/securityClassification-6VMVochwUWoRemove classification from folder
Parameters
| Name | In | Required | Type |
|---|---|---|---|
folder_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Returns an empty response when the classification is successfully deleted. | — |
400 | Returned when the request parameters are not valid. | ClientError |
404 | Returns an error when the folder does not have any classification applied to it, or when the user does not have access to the folder. * `instance_not_found` - An instance of the classification metadata template with the was not found on this folder. * `not_found` - The folder was not found, or the user does not have access to the folder. | ClientError |
405 | Returned when the method was not allowed. | ClientError |
default | An unexpected client error. | ClientError |
Collaborations4
Collaborations define access permissions for users and groups to files and folders, similar to access control lists.
POST/collaborationsCreate collaboration
Parameters
| Name | In | Required | Type |
|---|---|---|---|
fields | query | no | array |
notify | query | no | boolean |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns a new collaboration object. | Collaboration |
403 | Returns an error when the user does not have the right permissions to create the collaboration. * `forbidden_by_policy`: Creating a collaboration is forbidden due to information barrier restrictions. | ClientError |
default | An unexpected client error. | ClientError |
GET/collaborations/{collaboration_id}Get collaboration
Parameters
| Name | In | Required | Type |
|---|---|---|---|
collaboration_id | path | yes | string |
fields | query | no | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a collaboration object. | Collaboration |
default | An unexpected client error. | ClientError |
PUT/collaborations/{collaboration_id}Update collaboration
Parameters
| Name | In | Required | Type |
|---|---|---|---|
collaboration_id | path | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns an updated collaboration object unless the owner has changed. | Collaboration |
204 | If the role is changed to `owner`, the collaboration is deleted and a new collaboration is created. The previous `owner` of the old collaboration will be a `co-owner` on the new collaboration. | — |
403 | Returns an error if the authenticated user does not have the right permissions to update the collaboration. Additionally, this error may occur when attempting to update the `expires_at` field for the collaboration without the **Automatically remove invited collaborators: Allow folder owners to extend the expiry date** setting enabled in the admin dashboard of the enterprise. | ClientError |
default | An unexpected client error. | ClientError |
DELETE/collaborations/{collaboration_id}Remove collaboration
Parameters
| Name | In | Required | Type |
|---|---|---|---|
collaboration_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | A blank response is returned if the collaboration was successfully deleted. | — |
default | An unexpected client error. | ClientError |
Collaborations (List)4
A set of endpoints used to retrieve file, folder, pending, and group collaborations.
GET/collaborationsList pending collaborations
Parameters
| Name | In | Required | Type |
|---|---|---|---|
status | query | yes | string |
fields | query | no | array |
offset | query | no | integer |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a collection of pending collaboration objects. If the user has no pending collaborations, the collection will be empty. | CollaborationsOffsetPaginated |
default | An unexpected client error. | ClientError |
GET/files/{file_id}/collaborationsList file collaborations
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
fields | query | no | array |
limit | query | no | integer |
marker | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a collection of collaboration objects. If there are no collaborations on this file an empty collection will be returned. This list includes pending collaborations, for which the `status` is set to `pending`, indicating invitations that have been sent but not yet accepted. | Collaborations |
default | An unexpected client error. | ClientError |
GET/folders/{folder_id}/collaborationsList folder collaborations
Parameters
| Name | In | Required | Type |
|---|---|---|---|
folder_id | path | yes | string |
fields | query | no | array |
limit | query | no | integer |
marker | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a collection of collaboration objects. If there are no collaborations on this folder an empty collection will be returned. This list includes pending collaborations, for which the `status` is set to `pending`, indicating invitations that have been sent but not yet accepted. | Collaborations |
default | An unexpected client error. | ClientError |
GET/groups/{group_id}/collaborationsList group collaborations
Parameters
| Name | In | Required | Type |
|---|---|---|---|
group_id | path | yes | string |
limit | query | no | integer |
offset | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a collection of collaboration objects. If there are no collaborations, an empty collection will be returned. | CollaborationsOffsetPaginated |
default | An unexpected client error. | ClientError |
Collections3
Collections are a way to group files, folders, and web links without putting them all into a folder.
GET/collectionsList all collections
Parameters
| Name | In | Required | Type |
|---|---|---|---|
fields | query | no | array |
offset | query | no | integer |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns all collections for the given user. | Collections |
default | An unexpected client error. | ClientError |
GET/collections/{collection_id}Get collection by ID
Parameters
| Name | In | Required | Type |
|---|---|---|---|
collection_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns an array of items in the collection. | Collection |
default | An unexpected client error. | ClientError |
GET/collections/{collection_id}/itemsList collection items
Parameters
| Name | In | Required | Type |
|---|---|---|---|
collection_id | path | yes | string |
fields | query | no | array |
offset | query | no | integer |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns an array of items in the collection. | ItemsOffsetPaginated |
default | An unexpected client error. | ClientError |
Comments5
Comments are messages generated users on files, allowing users to collaborate on a file, discussing any feedback they might have on the content.
POST/commentsCreate comment
Parameters
| Name | In | Required | Type |
|---|---|---|---|
fields | query | no | array |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns the newly created comment object. Not all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields. | Comment--Full |
default | An unexpected client error. | ClientError |
GET/comments/{comment_id}Get comment
Parameters
| Name | In | Required | Type |
|---|---|---|---|
comment_id | path | yes | string |
fields | query | no | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a full comment object. | Comment--Full |
default | An unexpected client error. | ClientError |
PUT/comments/{comment_id}Update comment
Parameters
| Name | In | Required | Type |
|---|---|---|---|
comment_id | path | yes | string |
fields | query | no | array |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the updated comment object. | Comment--Full |
default | An unexpected client error. | ClientError |
DELETE/comments/{comment_id}Remove comment
Parameters
| Name | In | Required | Type |
|---|---|---|---|
comment_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Returns an empty response when the comment has been deleted. | — |
default | An unexpected client error. | ClientError |
GET/files/{file_id}/commentsList file comments
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
fields | query | no | array |
limit | query | no | integer |
offset | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a collection of comment objects. If there are no comments on this file an empty collection will be returned. | Comments |
default | An unexpected client error. | ClientError |
Device pinners3
Device pinners allow enterprises to control what devices can use native Box applications.
GET/device_pinners/{device_pinner_id}Get device pin
Parameters
| Name | In | Required | Type |
|---|---|---|---|
device_pinner_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns information about a single device pin. | DevicePinner |
default | An unexpected client error. | ClientError |
DELETE/device_pinners/{device_pinner_id}Remove device pin
Parameters
| Name | In | Required | Type |
|---|---|---|---|
device_pinner_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Returns an empty response when the pin has been deleted. | — |
default | An unexpected client error. | ClientError |
GET/enterprises/{enterprise_id}/device_pinnersList enterprise device pins
Parameters
| Name | In | Required | Type |
|---|---|---|---|
enterprise_id | path | yes | string |
marker | query | no | string |
limit | query | no | integer |
direction | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a list of device pins for a given enterprise. | DevicePinners |
default | An unexpected client error. | ClientError |
Domain restrictions (User exemptions)4
A set of endpoints that allow exempting users from restrictions imposed by the list of allowed collaboration domains for a specific enterprise.
GET/collaboration_whitelist_exempt_targetsList users exempt from collaboration domain restrictions
Parameters
| Name | In | Required | Type |
|---|---|---|---|
marker | query | no | string |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a collection of user exemptions. | CollaborationAllowlistExemptTargets |
default | An unexpected client error. | ClientError |
POST/collaboration_whitelist_exempt_targetsCreate user exemption from collaboration domain restrictions
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a new exemption entry. | CollaborationAllowlistExemptTarget |
default | An unexpected client error. | ClientError |
GET/collaboration_whitelist_exempt_targets/{collaboration_whitelist_exempt_target_id}Get user exempt from collaboration domain restrictions
Parameters
| Name | In | Required | Type |
|---|---|---|---|
collaboration_whitelist_exempt_target_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the user's exempted from the list of collaboration domains. | CollaborationAllowlistExemptTarget |
default | An unexpected client error. | ClientError |
DELETE/collaboration_whitelist_exempt_targets/{collaboration_whitelist_exempt_target_id}Remove user from list of users exempt from domain restrictions
Parameters
| Name | In | Required | Type |
|---|---|---|---|
collaboration_whitelist_exempt_target_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | A blank response is returned if the exemption was successfully deleted. | — |
default | An unexpected client error. | ClientError |
Domain restrictions for collaborations4
A set of endpoints that manage domains for which users can collaborate with files and folders in an enterprise.
GET/collaboration_whitelist_entriesList allowed collaboration domains
Parameters
| Name | In | Required | Type |
|---|---|---|---|
marker | query | no | string |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a collection of domains that are allowed for collaboration. | CollaborationAllowlistEntries |
default | An unexpected client error. | ClientError |
POST/collaboration_whitelist_entriesAdd domain to list of allowed collaboration domains
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a new entry on the list of allowed domains. | CollaborationAllowlistEntry |
default | An unexpected client error. | ClientError |
GET/collaboration_whitelist_entries/{collaboration_whitelist_entry_id}Get allowed collaboration domain
Parameters
| Name | In | Required | Type |
|---|---|---|---|
collaboration_whitelist_entry_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns an entry on the list of allowed domains. | CollaborationAllowlistEntry |
default | An unexpected client error. | ClientError |
DELETE/collaboration_whitelist_entries/{collaboration_whitelist_entry_id}Remove domain from list of allowed collaboration domains
Parameters
| Name | In | Required | Type |
|---|---|---|---|
collaboration_whitelist_entry_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | A blank response is returned if the entry was successfully deleted. | — |
default | An unexpected client error. | ClientError |
Downloads1
Downloads allow saving files to the application's server, or directly by the end user in a browser.
GET/files/{file_id}/contentDownload file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
range | header | no | string |
boxapi | header | no | string |
version | query | no | string |
access_token | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the requested file if the client has the **follow redirects** setting enabled to automatically follow HTTP `3xx` responses as redirects. If not, the request will return `302` instead. For details, see the [download file guide](https://developer.box.com/guides/downloads/file#download-url). | — |
202 | If the file is not ready to be downloaded yet `Retry-After` header will be returned indicating the time in seconds after which the file will be available for the client to download. This response can occur when the file was uploaded immediately before the download request. | — |
302 | If the file is available for download the response will include a `Location` header for the file on `dl.boxcloud.com`. The `dl.boxcloud.com` URL is not persistent and clients will need to follow the redirect to actually download the file. | — |
default | An unexpected client error. | ClientError |
Email aliases3
Email aliases provide a list of emails additional to the user's primary login email.
GET/users/{user_id}/email_aliasesList user's email aliases
Parameters
| Name | In | Required | Type |
|---|---|---|---|
user_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a collection of email aliases. | EmailAliases |
default | An unexpected client error. | ClientError |
POST/users/{user_id}/email_aliasesCreate email alias
Parameters
| Name | In | Required | Type |
|---|---|---|---|
user_id | path | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns the newly created email alias object. | EmailAlias |
default | An unexpected client error. | ClientError |
DELETE/users/{user_id}/email_aliases/{email_alias_id}Remove email alias
Parameters
| Name | In | Required | Type |
|---|---|---|---|
user_id | path | yes | string |
email_alias_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Removes the alias and returns an empty response. | — |
default | An unexpected client error. | ClientError |
Events2
Events provide a way for an application to subscribe to any actions performed by any user, users, or service in an enterprise.
GET/eventsList user and enterprise events
Parameters
| Name | In | Required | Type |
|---|---|---|---|
stream_type | query | no | string |
stream_position | query | no | string |
limit | query | no | integer |
event_type | query | no | array |
created_after | query | no | string |
created_before | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a list of event objects. Events objects are returned in pages, with each page (chunk) including a list of event objects. The response includes a `chunk_size` parameter indicating how many events were returned in this chunk, as well as the next `stream_position` that can be queried. | Events |
default | An unexpected client error. | ClientError |
OPTIONS/eventsGet events long poll endpoint
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a paginated array of servers that can be used instead of the regular endpoints for long-polling events. | RealtimeServers |
default | An unexpected client error. | ClientError |
File requests4
File Requests provide a fast and secure way to request files and associated metadata from anyone. Users can create new file requests based on an existing file request, update file request settings, activate, deactivate, and delete file requests programmatically.
GET/file_requests/{file_request_id}Get file request
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_request_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a file request object. | FileRequest |
401 | Returned when the access token provided in the `Authorization` header is not recognized or not provided. | ClientError |
404 | Returned if the file request is not found, or the user does not have access to the associated folder. | ClientError |
405 | Returned if the `file_request_id` is not in a recognized format. | ClientError |
default | An unexpected client error. | ClientError |
PUT/file_requests/{file_request_id}Update file request
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_request_id | path | yes | string |
if-match | header | no | string |
Request body
application/json — FileRequestUpdateRequest
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the updated file request object. | FileRequest |
401 | Returned when the access token provided in the `Authorization` header is not recognized or not provided. | ClientError |
403 | Returned if the user does not have all the permissions to complete the update. * `access_denied_insufficient_permissions` when the authenticated user does not have access to update the file request. | ClientError |
404 | Returned if the file request is not found, or the user does not have access to the associated folder. | ClientError |
405 | Returned if the `file_request_id` is not in a recognized format. | ClientError |
412 | Returns an error when the `If-Match` header does not match the current `etag` value of the file request. This indicates that the file request has changed since it was last requested. | ClientError |
default | An unexpected client error. | ClientError |
DELETE/file_requests/{file_request_id}Delete file request
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_request_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Returns an empty response when the file request has been successfully deleted. | — |
401 | Returned when the access token provided in the `Authorization` header is not recognized or not provided. | ClientError |
404 | Returned if the file request is not found or has already been deleted, or the user does not have access to the associated folder. | ClientError |
405 | Returned if the `file_request_id` is not in a recognized format. | ClientError |
default | An unexpected client error. | ClientError |
POST/file_requests/{file_request_id}/copyCopy file request
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_request_id | path | yes | string |
Request body
application/json — FileRequestCopyRequest
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns updated file request object. | FileRequest |
401 | Returned when the access token provided in the `Authorization` header is not recognized or not provided. | ClientError |
403 | Returned if the user does not have all the permissions to complete the update. * `access_denied_insufficient_permissions` when the authenticated user does not have access to update the file request. | ClientError |
404 | Returned if the file request is not found, or the user does not have access to the associated folder. | ClientError |
405 | Returned if the `file_request_id` is not in a recognized format. | ClientError |
default | An unexpected client error. | ClientError |
File version legal holds2
A legal hold is a process that an enterprise can use to preserve all forms of potentially relevant information when litigation is pending or reasonably anticipated. A File Version Legal Hold represents all the policies that are assigned to a specific file version.
GET/file_version_legal_holdsList file version legal holds
Parameters
| Name | In | Required | Type |
|---|---|---|---|
policy_id | query | yes | string |
marker | query | no | string |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the list of file version legal holds for a specific legal hold policy. | FileVersionLegalHolds |
default | An unexpected client error. | ClientError |
GET/file_version_legal_holds/{file_version_legal_hold_id}Get file version legal hold
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_version_legal_hold_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the legal hold policy assignments for the file version. | FileVersionLegalHold |
default | An unexpected client error. | ClientError |
File version retentions2
A retention policy blocks permanent deletion of content for a specified amount of time. A file version retention is a record for a retained file.
GET/file_version_retentionsList file version retentions
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | query | no | string |
file_version_id | query | no | string |
policy_id | query | no | string |
disposition_action | query | no | string |
disposition_before | query | no | string |
disposition_after | query | no | string |
limit | query | no | integer |
marker | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a list of all file version retentions for the enterprise. | FileVersionRetentions |
default | An unexpected client error. | ClientError |
GET/file_version_retentions/{file_version_retention_id}Get retention on file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_version_retention_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a file version retention object. | FileVersionRetention |
default | An unexpected client error. | ClientError |
File versions5
A set of endpoints used to manage specific versions of a file.
GET/files/{file_id}/versionsList all file versions
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
fields | query | no | array |
limit | query | no | integer |
offset | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns an array of past versions for this file. | FileVersions |
default | An unexpected client error. | ClientError |
POST/files/{file_id}/versions/currentPromote file version
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
fields | query | no | array |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns a newly created file version object. | FileVersion--Full |
default | An unexpected client error. | ClientError |
GET/files/{file_id}/versions/{file_version_id}Get file version
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
fields | query | no | array |
file_version_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a specific version of a file. Not all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields. | FileVersion--Full |
default | An unexpected client error. | ClientError |
PUT/files/{file_id}/versions/{file_version_id}Restore file version
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
file_version_id | path | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a restored file version object. | FileVersion--Full |
default | An unexpected client error. | ClientError |
DELETE/files/{file_id}/versions/{file_version_id}Remove file version
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
file_version_id | path | yes | string |
if-match | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Returns an empty response when the file has been successfully deleted. | — |
default | An unexpected client error. | ClientError |
Files6
Files, together with Folders, are at the core of the Box API. Files can be uploaded and downloaded, as well as hold important metadata information about the content.
OPTIONS/files/contentPreflight check before upload
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | If the check passed, the response will include a session URL that can be used to upload the file to. | UploadUrl |
409 | If the check did not pass, the response will include some details on why it did not pass. | ConflictError |
default | An unexpected client error. | ClientError |
GET/files/{file_id}Get file information
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
fields | query | no | array |
if-none-match | header | no | string |
boxapi | header | no | string |
x-rep-hints | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a file object. Not all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields. | File--Full |
304 | Returns an empty response when the `If-None-Match` header matches the current `etag` value of the folder. This indicates that the folder has not changed since it was last requested. | — |
401 | Returned when the access token provided in the `Authorization` header is not recognized or not provided. | ClientError |
404 | Returned if the file is not found, or the user does not have access to the file. | ClientError |
405 | Returned if the `file_id` is not in a recognized format. | ClientError |
415 | Returns an error if an action is performed on a file with an incorrect media type. * `unsupported_media_type` when requesting an `expiring_embed_link` for a file that is not supported by Box Embed. | ClientError |
default | An unexpected client error. | ClientError |
PUT/files/{file_id}Update file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
fields | query | no | array |
if-match | header | no | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a file object. Not all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields. | File--Full |
400 | Returned when the new retention time > maximum retention length. | ClientError |
401 | Returned when the access token provided in the `Authorization` header is not recognized or not provided. | ClientError |
403 | Returned if the user does not have all the permissions to complete the update. * `access_denied_insufficient_permissions` returned when the authenticated user does not have access to the destination folder to move the file to. * Returned when retention time is shorter or equal to current retention timestamp. * Returned when a `file_id` that is not under retention is entered. * Returned when a file that is retained but the disposition action is set to `remove_retention` * `forbidden_by_policy` is returned if copying a folder is forbidden due to information barrier restrictions. | ClientError |
404 | Returned if the file is not found, or the user does not have access to the file. | ClientError |
405 | Returned if the `file_id` is not in a recognized format. | ClientError |
412 | Returns an error when the `If-Match` header does not match the current `etag` value of the file. This indicates that the file has changed since it was last requested. | ClientError |
default | An unexpected client error. | ClientError |
DELETE/files/{file_id}Delete file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
if-match | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Returns an empty response when the file has been successfully deleted. | — |
401 | Returned when the access token provided in the `Authorization` header is not recognized or not provided. | ClientError |
404 | Returned if the file is not found or has already been deleted, or the user does not have access to the file. | ClientError |
405 | Returned if the `file_id` is not in a recognized format. | ClientError |
412 | Returns an error when the `If-Match` header does not match the current `etag` value of the file. This indicates that the file has changed since it was last requested. | ClientError |
default | An unexpected client error. | ClientError |
POST/files/{file_id}/copyCopy file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
fields | query | no | array |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns a new file object representing the copied file. Not all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields. | File--Full |
304 | Returns an empty response when the `If-None-Match` header matches the current `etag` value of the file. This indicates that the file has not changed since it was last requested. | — |
400 | Returns an error if some of the parameters are missing or not valid. * `bad_request` when a parameter is missing. | ClientError |
403 | Returns an error when the user does not have the right permissions to create the copy a file. * `forbidden_by_policy`: Returned if copying a file is forbidden due to information barrier restrictions. | ClientError |
404 | Returns an error if either the source file or the destination folder could not be found, or the authenticated user does not have access to either. * `not_found` when the authenticated user does not have access to the source file or the destination folder. | ClientError |
409 | `operation_blocked_temporary`: Returned if either of the destination or source folders is locked due to another move, copy, delete or restore operation in process. The operation can be retried at a later point. `item_name_in_use` when a folder with the same name already exists. | ClientError |
default | An unexpected client error. | ClientError |
GET/files/{file_id}/thumbnail.{extension}Get file thumbnail
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
extension | path | yes | string |
min_height | query | no | integer |
min_width | query | no | integer |
max_height | query | no | integer |
max_width | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | When a thumbnail can be created the thumbnail data will be returned in the body of the response. | — |
202 | Sometimes generating a thumbnail can take a few seconds. In these situations the API returns a `Location`-header pointing to a placeholder graphic for this file type. The placeholder graphic can be used in a user interface until the thumbnail generation has completed. The `Retry-After`-header indicates when to the thumbnail will be ready. At that time, retry this endpoint to retrieve the thumbnail. | — |
302 | Returns an error when Box is not able to create a thumbnail for this file type. Instead, a `Location`-header pointing to a placeholder graphic for this file type will be returned. | — |
400 | Returns an error if some of the parameters are missing or not valid. * `requested_preview_unavailable` - an incorrect dimension was requested. This will happen if the dimension requested is larger or smaller than the available file sizes for the thumbnail format, or when when any of the size constraints contradict each other. | ClientError |
403 | Returned when the access token provided in the `Authorization` header is not recognized or not provided. | ClientError |
404 | Returned if the file is not found, or the user does not have access to the file, or for additional reasons. * `preview_cannot_be_generated` - Box does not support thumbnails for this type of file. | ClientError |
default | An unexpected client error. | ClientError |
Folder Locks3
Folder locks define access restrictions placed by folder owners to prevent specific folders from being moved or deleted.
GET/folder_locksList folder locks
Parameters
| Name | In | Required | Type |
|---|---|---|---|
folder_id | query | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns details for all folder locks applied to the folder, including the lock type and user that applied the lock. | FolderLocks |
403 | Returned when the access token provided in the `Authorization` header is not recognized or not provided. | ClientError |
404 | Returned if the folder is not found, or the user does not have access to the folder. | ClientError |
405 | Returned if the `folder_id` is not in a recognized format. | ClientError |
default | An unexpected client error. | ClientError |
POST/folder_locksCreate folder lock
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the instance of the folder lock that was applied to the folder, including the user that applied the lock and the operations set. | FolderLock |
400 | Returns an error when the request body is not valid. * `schema_validation_failed` - The request body contains a value for a field that either does not exist, or for which the value or type does not match the expected field type. An example might be an unknown option for an `enum` or `multiSelect` field. | ClientError |
404 | Returns an error when the folder was not found. * `not_found` - The folder could not be found, the user does not have access to the folder, or the user making call is not an owner or co-owner of folder. | ClientError |
default | An unexpected client error. | ClientError |
DELETE/folder_locks/{folder_lock_id}Delete folder lock
Parameters
| Name | In | Required | Type |
|---|---|---|---|
folder_lock_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Returns an empty response when the folder lock is successfully deleted. | — |
403 | Returns an error if the user does not have the required access to perform the action. * `access_denied_insufficient_permissions`: Returned when the user does not have access to the folder. * `insufficient_scope`: Returned an error if the application does not have the right scope to delete folders. Make sure your application has been configured to read and write all files and folders stored in Box. | ClientError |
404 | Returns an error if the folder could not be found, or the authenticated user does not have access to the folder. * `not_found` when the authenticated user does not have access to the folder. | ClientError |
default | An unexpected client error. | ClientError |
Folders6
Folders, together with Files, are at the core of the Box API. Folders can be uploaded and downloaded, as well as hold important metadata information about the content.
POST/foldersCreate folder
Parameters
| Name | In | Required | Type |
|---|---|---|---|
fields | query | no | array |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns a folder object. Not all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields. | Folder--Full |
400 | Returns an error if some of the parameters are missing or not valid. * `bad_request` when a parameter is missing or incorrect. * `item_name_too_long` when the folder name is too long. * `item_name_invalid` when the folder name contains non-valid characters. | ClientError |
403 | Returns an error if the user does not have the required access to perform the action. This might be because they don't have access to the folder or parent folder, or because the application does not have permission to write files and folders. | ClientError |
404 | Returns an error if the parent folder could not be found, or the authenticated user does not have access to the parent folder. * `not_found` when the authenticated user does not have access to the parent folder. | ClientError |
409 | `operation_blocked_temporary`: Returned if either of the destination or source folders is locked due to another move, copy, delete or restore operation in process. The operation can be retried at a later point. `item_name_in_use`: Returned if a folder with the name already exists in the parent folder. | ClientError |
default | An unexpected client error. | ClientError |
GET/folders/{folder_id}Get folder information
Parameters
| Name | In | Required | Type |
|---|---|---|---|
folder_id | path | yes | string |
fields | query | no | array |
if-none-match | header | no | string |
boxapi | header | no | string |
sort | query | no | string |
direction | query | no | string |
offset | query | no | integer |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a folder, including the first 100 entries in the folder. If you used query parameters like `sort`, `direction`, `offset`, or `limit` the *folder items list* will be affected accordingly. To fetch more items within the folder, use the [Get items in a folder](https://developer.box.com/reference/get-folders-id-items)) endpoint. Not all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields. | Folder--Full |
304 | Returns an empty response when the `If-None-Match` header matches the current `etag` value of the folder. This indicates that the folder has not changed since it was last requested. | — |
403 | Returned when the access token provided in the `Authorization` header is not recognized or not provided. | ClientError |
404 | Returned if the folder is not found, or the user does not have access to the folder. | ClientError |
405 | Returned if the `folder_id` is not in a recognized format. | ClientError |
default | An unexpected client error. | ClientError |
PUT/folders/{folder_id}Update folder
Parameters
| Name | In | Required | Type |
|---|---|---|---|
folder_id | path | yes | string |
fields | query | no | array |
if-match | header | no | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a folder object for the updated folder Not all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields. If the user is moving folders with a large number of items in all of their descendants, the call will be run asynchronously. If the operation is not completed within 10 minutes, the user will receive a 200 OK response, and the operation will continue running. | Folder--Full |
400 | Returns an error if some of the parameters are missing or not valid, or if a folder lock is preventing a move operation. * `bad_request` when a parameter is missing or incorrect. This error also happens when a password is set for a shared link with an access type of `open`. * `item_name_too_long` when the folder name is too long. * `item_name_invalid` when the folder name contains non-valid characters. | ClientError |
403 | Returns an error if the user does not have the required access to perform the action. * `access_denied_insufficient_permissions`: Returned when the user does not have access to the folder or parent folder, or if the folder is being moved and a folder lock has been applied to prevent such operations. * `insufficient_scope`: Returned an error if the application does not have the right scope to update folders. Make sure your application has been configured to read and write all files and folders stored in Box. * `forbidden`: Returned when the user is not allowed to perform this action for other users. This can include trying to create a Shared Link with a `company` access level on a free account. * `forbidden_by_policy`: Returned if copying a folder is forbidden due to information barrier restrictions. Returns an error if there are too many actions in the request body. * `operation_limit_exceeded`: Returned when the user passes any parameters in addition to the `parent.id` in the request body. The calls to this endpoint have to be split up. The first call needs to include only the `parent.id`, the next call can include other parameters. | ClientError |
404 | Returns an error if the folder or parent folder could not be found, or the authenticated user does not have access to either folder. * `not_found` when the authenticated user does not have access to the folder or parent folder. | ClientError |
409 | `operation_blocked_temporary`: Returned if either of the destination or source folders is locked due to another move, copy, delete or restore operation in progress. The operation can be retried at a later point. `item_name_in_use`: Returned if a folder with the name already exists in the parent folder. | ClientError |
412 | Returns an error when the `If-Match` header does not match the current `etag` value of the folder. This indicates that the folder has changed since it was last requested. | ClientError |
503 | Returns an error when the operation takes longer than 600 seconds. The operation will continue after this response has been returned. | ClientError |
default | An unexpected client error. | ClientError |
DELETE/folders/{folder_id}Delete folder
Parameters
| Name | In | Required | Type |
|---|---|---|---|
folder_id | path | yes | string |
if-match | header | no | string |
recursive | query | no | boolean |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Returns an empty response when the folder is successfully deleted or moved to the trash. | — |
400 | Returns an error if the user makes a bad request. * `folder_not_empty`: Returned if the folder is not empty. Use the `recursive` query parameter to recursively delete the folder and its contents. | ClientError |
403 | Returns an error if the user does not have the required access to perform the action. * `access_denied_insufficient_permissions`: Returned when the user does not have access to the folder, or when a folder lock has been applied to the folder to prevent deletion. * `insufficient_scope`: Returned an error if the application does not have the right scope to delete folders. Make sure your application has been configured to read and write all files and folders stored in Box. | ClientError |
404 | Returns an error if the folder could not be found, or the authenticated user does not have access to the folder. * `not_found` when the authenticated user does not have access to the folder. | ClientError |
409 | `operation_blocked_temporary`: Returned if the folder is locked due to another move, copy, delete or restore operation in progress. The operation can be retried at a later point. | ClientError |
412 | Returns an error when the `If-Match` header does not match the current `etag` value of the folder. This indicates that the folder has changed since it was last requested. | ClientError |
503 | Returns an error when the operation takes longer than 600 seconds. The operation will continue after this response has been returned. | ClientError |
default | An unexpected client error. | ClientError |
POST/folders/{folder_id}/copyCopy folder
Parameters
| Name | In | Required | Type |
|---|---|---|---|
folder_id | path | yes | string |
fields | query | no | array |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns a new folder object representing the copied folder. Not all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields. | Folder--Full |
304 | Returns an empty response when the `If-None-Match` header matches the current `etag` value of the folder. This indicates that the folder has not changed since it was last requested. | — |
400 | Returns an error if some of the parameters are missing or not valid. * `bad_request` when a parameter is missing. * `item_name_too_long` when the new folder name is too long. | ClientError |
403 | Returns an error when the user does not have the right permissions to copy a folder. * `forbidden_by_policy`: Returned if copying a folder is forbidden due to information barrier restrictions. | ClientError |
404 | Returns an error if either the source or destination folder could not be found, or the authenticated user does not have access to either folders. * `not_found` when the authenticated user does not have access to the parent folder. | ClientError |
409 | Returns an error if a folder by this name already exists in the destination folder, or if the destination folder is locked. * `item_name_in_use` when a folder with the same name already exists. | ClientError |
500 | Returns an error when trying to copy the root folder. | ClientError |
default | An unexpected client error. | ClientError |
GET/folders/{folder_id}/itemsList items in folder
Parameters
| Name | In | Required | Type |
|---|---|---|---|
folder_id | path | yes | string |
fields | query | no | array |
usemarker | query | no | boolean |
marker | query | no | string |
offset | query | no | integer |
limit | query | no | integer |
boxapi | header | no | string |
sort | query | no | string |
direction | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a collection of files, folders, and web links contained in a folder. | Items |
403 | Returned when the access token provided in the `Authorization` header is not recognized or not provided. | ClientError |
404 | Returned if the folder is not found, or the user does not have access to the folder. | ClientError |
405 | Returned if the `folder_id` is not in a recognized format. | ClientError |
default | An unexpected client error. | ClientError |
Integration mappings8
Integration Mappings allow the users to manage where content from partner apps is stored in Box.
GET/integration_mappings/slackList Slack integration mappings
Parameters
| Name | In | Required | Type |
|---|---|---|---|
marker | query | no | string |
limit | query | no | integer |
partner_item_type | query | no | string |
partner_item_id | query | no | string |
box_item_id | query | no | string |
box_item_type | query | no | string |
is_manually_created | query | no | boolean |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a collection of integration mappings. | IntegrationMappings |
400 | The server cannot or will not process the request due to an apparent client error. | ClientError |
404 | Returns a `not_found` error if the integration mapping could not be found. | ClientError |
default | An unexpected client error. | ClientError |
POST/integration_mappings/slackCreate Slack integration mapping
Request body
application/json — IntegrationMappingSlackCreateRequest
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns the created integration mapping. | IntegrationMapping |
400 | Returns a `bad_request` if an incorrect `options` was supplied or the Box folder cannot be mapped to this `partner_item_id`. Error codes: * `SERVICE_ACCOUNT_IS_NOT_A_COOWNER_OR_OWNER` - service account doesn't have co-owner collaboration or is not an owner of the `box_item_id`, * `CHANNEL_ALREADY_MAPPED` - channel is already mapped to another `box_item_id`, * `CHANNEL_NOT_FOUND` - channel was not found, * `CHANNEL_NOT_SUITABLE_FOR_CFS` - connect channel, not suitable for Box as Content layer for Slack, * `BOX_ENTERPRISE_MISMATCH` - Box folder must be owned by the enterprise, which is configured to use Box as Content layer for Slack, * `CFS_DISABLED` - Box as Content layer for Slack must be enabled for a provided Slack workspace or organization * `BOX_FOLDER_EXTERNALLY_OWNED` - Box folder must be internally owned to the admin's enterprise, * `JWT_APP_NOT_AUTHORIZED` - JWT authorization error. | ClientError |
404 | Returns a `not_found` error if the integration mapping could not be found. | ClientError |
default | An unexpected client error. | ClientError |
PUT/integration_mappings/slack/{integration_mapping_id}Update Slack integration mapping
Parameters
| Name | In | Required | Type |
|---|---|---|---|
integration_mapping_id | path | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the updated integration mapping object. | IntegrationMapping |
400 | Returns a `bad_request` if an incorrect `options` was supplied or the Box folder cannot be mapped to this `partner_item`. Error codes: * `SERVICE_ACCOUNT_IS_NOT_A_COOWNER_OR_OWNER` - service account doesn't have co-owner collaboration or is not an owner of the `box_item_id`, * `BOX_FOLDER_EXTERNALLY_OWNED` - Box folder must be internally owned to the admin's enterprise, * `JWT_APP_NOT_AUTHORIZED` - JWT authorization error. | ClientError |
404 | Returns `not_found` if integration mapping object was not found. | ClientError |
default | An unexpected client error. | ClientError |
DELETE/integration_mappings/slack/{integration_mapping_id}Delete Slack integration mapping
Parameters
| Name | In | Required | Type |
|---|---|---|---|
integration_mapping_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Empty body in response. | — |
404 | Returns a `not_found` error if the integration mapping could not be found. | ClientError |
default | An unexpected client error. | ClientError |
GET/integration_mappings/teamsList Teams integration mappings
Parameters
| Name | In | Required | Type |
|---|---|---|---|
partner_item_type | query | no | string |
partner_item_id | query | no | string |
box_item_id | query | no | string |
box_item_type | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a collection of integration mappings. | IntegrationMappingsTeams |
400 | The server cannot or will not process the request due to an apparent client error. | ClientError |
404 | Returns a `not_found` error if the integration mapping could not be found. | ClientError |
default | An unexpected client error. | ClientError |
POST/integration_mappings/teamsCreate Teams integration mapping
Request body
application/json — IntegrationMappingTeamsCreateRequest
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns the created integration mapping. | IntegrationMappingTeams |
400 | Returns a `bad_request` if an incorrect `options` was supplied or the Box folder cannot be mapped to this `partner_item_id`. Error codes: * `SERVICE_ACCOUNT_IS_NOT_A_COOWNER_OR_OWNER` - service account doesn't have co-owner collaboration or is not an owner of the `box_item_id`, * `CHANNEL_ALREADY_MAPPED` - channel is already mapped to another `box_item_id`, * `TEAM_ALREADY_MAPPED` - team is already mapped to another `box_item_id`, * `BOX_ENTERPRISE_MISMATCH` - Box folder must be owned by the enterprise, which is configured to use Box as Content layer for Teams, * `BOX_FOLDER_EXTERNALLY_OWNED` - Box folder must be internally owned to the admin's enterprise * `FOLDER_ALREADY_MAPPED` - Box folder must not be mapped to another integration mapping. | ClientError |
404 | Returns a `not_found` error if the integration mapping, record or folder could not be found. | ClientError |
default | An unexpected client error. | ClientError |
PUT/integration_mappings/teams/{integration_mapping_id}Update Teams integration mapping
Parameters
| Name | In | Required | Type |
|---|---|---|---|
integration_mapping_id | path | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the updated integration mapping object. | IntegrationMappingTeams |
400 | Returns a `bad_request` if an incorrect `options` was supplied or the Box folder cannot be mapped to this `partner_item`. Error codes: * `SERVICE_ACCOUNT_IS_NOT_A_COOWNER_OR_OWNER` - service account doesn't have co-owner collaboration or is not an owner of the `box_item_id`, * `BOX_FOLDER_EXTERNALLY_OWNED` - Box folder must be internally owned to the admin's enterprise, * `FOLDER_ALREADY_MAPPED` - Box folder must not be mapped to another integration mapping. | ClientError |
404 | Returns `not_found` if integration mapping object was not found. | ClientError |
default | An unexpected client error. | ClientError |
DELETE/integration_mappings/teams/{integration_mapping_id}Delete Teams integration mapping
Parameters
| Name | In | Required | Type |
|---|---|---|---|
integration_mapping_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Empty body in response. | — |
404 | Returns a `not_found` error if the integration mapping could not be found. | ClientError |
default | An unexpected client error. | ClientError |
Group memberships6
Group memberships signify that a user is a part of the group.
POST/group_membershipsAdd user to group
Parameters
| Name | In | Required | Type |
|---|---|---|---|
fields | query | no | array |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns a new group membership object. | GroupMembership |
403 | Returns an error when the user cannot be added to a group. * `forbidden_by_policy`: Adding a user to a group is forbidden due to information barrier restrictions. | ClientError |
default | An unexpected client error. | ClientError |
GET/group_memberships/{group_membership_id}Get group membership
Parameters
| Name | In | Required | Type |
|---|---|---|---|
group_membership_id | path | yes | string |
fields | query | no | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the group membership object. | GroupMembership |
default | An unexpected client error. | ClientError |
PUT/group_memberships/{group_membership_id}Update group membership
Parameters
| Name | In | Required | Type |
|---|---|---|---|
group_membership_id | path | yes | string |
fields | query | no | array |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a new group membership object. | GroupMembership |
default | An unexpected client error. | ClientError |
DELETE/group_memberships/{group_membership_id}Remove user from group
Parameters
| Name | In | Required | Type |
|---|---|---|---|
group_membership_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | A blank response is returned if the membership was successfully deleted. | — |
default | An unexpected client error. | ClientError |
GET/groups/{group_id}/membershipsList members of group
Parameters
| Name | In | Required | Type |
|---|---|---|---|
group_id | path | yes | string |
limit | query | no | integer |
offset | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a collection of membership objects. If there are no memberships, an empty collection will be returned. | GroupMemberships |
default | An unexpected client error. | ClientError |
GET/users/{user_id}/membershipsList user's groups
Parameters
| Name | In | Required | Type |
|---|---|---|---|
user_id | path | yes | string |
limit | query | no | integer |
offset | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a collection of membership objects. If there are no memberships, an empty collection will be returned. | GroupMemberships |
default | An unexpected client error. | ClientError |
Groups5
Groups created in an enterprise.
GET/groupsList groups for enterprise
Parameters
| Name | In | Required | Type |
|---|---|---|---|
filter_term | query | no | string |
fields | query | no | array |
limit | query | no | integer |
offset | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a collection of group objects. If there are no groups, an empty collection will be returned. | Groups |
default | An unexpected client error. | ClientError |
POST/groupsCreate group
Parameters
| Name | In | Required | Type |
|---|---|---|---|
fields | query | no | array |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns the new group object. | Group--Full |
409 | Returns an error a conflict is stopping the group from being created. * `invalid_parameter`: Often returned if the group name is not unique in the enterprise. | ClientError |
default | An unexpected client error. | ClientError |
GET/groups/{group_id}Get group
Parameters
| Name | In | Required | Type |
|---|---|---|---|
group_id | path | yes | string |
fields | query | no | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the group object. | Group--Full |
default | An unexpected client error. | ClientError |
PUT/groups/{group_id}Update group
Parameters
| Name | In | Required | Type |
|---|---|---|---|
group_id | path | yes | string |
fields | query | no | array |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the updated group object. | Group--Full |
409 | Returns an error a conflict is stopping the group from being created. * `invalid_parameter`: Often returned if the group name is not unique in the enterprise. | ClientError |
default | An unexpected client error. | ClientError |
DELETE/groups/{group_id}Remove group
Parameters
| Name | In | Required | Type |
|---|---|---|---|
group_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | A blank response is returned if the group was successfully deleted. | — |
default | An unexpected client error. | ClientError |
Invites2
Invites are used to invite the user to an enterprise.
POST/invitesCreate user invite
Parameters
| Name | In | Required | Type |
|---|---|---|---|
fields | query | no | array |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a new invite object. | Invite |
404 | Returns `not_found` when user was not found. | ClientError |
default | An unexpected client error. | ClientError |
GET/invites/{invite_id}Get user invite status
Parameters
| Name | In | Required | Type |
|---|---|---|---|
invite_id | path | yes | string |
fields | query | no | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns an invite object. | Invite |
default | An unexpected client error. | ClientError |
Legal hold policies5
A legal hold is a process that an enterprise can use to preserve all forms of potentially relevant information when litigation is pending or reasonably anticipated.
GET/legal_hold_policiesList all legal hold policies
Parameters
| Name | In | Required | Type |
|---|---|---|---|
policy_name | query | no | string |
fields | query | no | array |
marker | query | no | string |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a list of legal hold policies. | LegalHoldPolicies |
default | An unexpected client error. | ClientError |
POST/legal_hold_policiesCreate legal hold policy
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns a new legal hold policy object. | LegalHoldPolicy |
400 | Returns an error if required parameters are missing, or neither `is_ongoing` or filter dates are specified. | ClientError |
409 | Returns an error if a policy with this name already exists. | ClientError |
default | An unexpected client error. | ClientError |
GET/legal_hold_policies/{legal_hold_policy_id}Get legal hold policy
Parameters
| Name | In | Required | Type |
|---|---|---|---|
legal_hold_policy_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a legal hold policy object. | LegalHoldPolicy |
default | An unexpected client error. | ClientError |
PUT/legal_hold_policies/{legal_hold_policy_id}Update legal hold policy
Parameters
| Name | In | Required | Type |
|---|---|---|---|
legal_hold_policy_id | path | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a new legal hold policy object. | LegalHoldPolicy |
409 | Returns an error if a policy with this name already exists. | ClientError |
default | An unexpected client error. | ClientError |
DELETE/legal_hold_policies/{legal_hold_policy_id}Remove legal hold policy
Parameters
| Name | In | Required | Type |
|---|---|---|---|
legal_hold_policy_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
202 | A blank response is returned if the policy was successfully deleted. | — |
default | An unexpected client error. | ClientError |
Legal hold policy assignments6
A Legal Hold Policy Assignment is a relation between a policy and custodian. In this case, as custodian can be a user, folder, file, or file version.
GET/legal_hold_policy_assignmentsList legal hold policy assignments
Parameters
| Name | In | Required | Type |
|---|---|---|---|
policy_id | query | yes | string |
assign_to_type | query | no | string |
assign_to_id | query | no | string |
marker | query | no | string |
limit | query | no | integer |
fields | query | no | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a list of legal hold policy assignments. | LegalHoldPolicyAssignments |
default | An unexpected client error. | ClientError |
POST/legal_hold_policy_assignmentsAssign legal hold policy
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns a new legal hold policy assignment. | LegalHoldPolicyAssignment |
default | An unexpected client error. | ClientError |
GET/legal_hold_policy_assignments/{legal_hold_policy_assignment_id}Get legal hold policy assignment
Parameters
| Name | In | Required | Type |
|---|---|---|---|
legal_hold_policy_assignment_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a legal hold policy object. | LegalHoldPolicyAssignment |
default | An unexpected client error. | ClientError |
DELETE/legal_hold_policy_assignments/{legal_hold_policy_assignment_id}Unassign legal hold policy
Parameters
| Name | In | Required | Type |
|---|---|---|---|
legal_hold_policy_assignment_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
202 | A blank response is returned if the assignment was successfully deleted. | — |
default | An unexpected client error. | ClientError |
GET/legal_hold_policy_assignments/{legal_hold_policy_assignment_id}/file_versions_on_holdList previous file versions for legal hold policy assignment
Parameters
| Name | In | Required | Type |
|---|---|---|---|
legal_hold_policy_assignment_id | path | yes | string |
marker | query | no | string |
limit | query | no | integer |
fields | query | no | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the list of previous file versions held under legal hold for a specific legal hold policy assignment. | FileVersionsOnHold |
default | An unexpected client error. | ClientError |
GET/legal_hold_policy_assignments/{legal_hold_policy_assignment_id}/files_on_holdList files with current file versions for legal hold policy assignment
Parameters
| Name | In | Required | Type |
|---|---|---|---|
legal_hold_policy_assignment_id | path | yes | string |
marker | query | no | string |
limit | query | no | integer |
fields | query | no | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the list of current file versions held under legal hold for a specific legal hold policy assignment. | FilesOnHold |
default | An unexpected client error. | ClientError |
Metadata cascade policies5
A metadata cascade policy describes how metadata instances applied to a folder should be applied to any item within that folder.
GET/metadata_cascade_policiesList metadata cascade policies
Parameters
| Name | In | Required | Type |
|---|---|---|---|
folder_id | query | yes | string |
owner_enterprise_id | query | no | string |
marker | query | no | string |
offset | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a list of metadata cascade policies. | MetadataCascadePolicies |
400 | Returns an error when any of the parameters are not in a valid format. | ClientError |
403 | Returns an error when the folder can not be accessed. This error often happens when accessing the root folder with ID `0`. | ClientError |
404 | Returns an error when the folder can not be found or the user does not have access to the folder. * `not_found` - The folder could not be found or the user does not have access to the folder. | ClientError |
default | An unexpected client error. | ClientError |
POST/metadata_cascade_policiesCreate metadata cascade policy
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns a new of metadata cascade policy. | MetadataCascadePolicy |
400 | Returns an error when any of the parameters are not in a valid format. * `bad_request` - Either the `scope`, `templateKey`, or `folder_id` are not in a valid format. | ClientError |
403 | Returns an error when trying to apply a policy to a restricted folder, for example the root folder with ID `0`. * `forbidden` - Although the folder ID was valid and the user has access to the folder, the policy could not be applied to this folder. | ClientError |
404 | Returns an error when the template or folder can not be found, or when the user does not have access to the folder or template. * `instance_tuple_not_found` - The template could not be found or the user does not have access to the template. * `not_found` - The folder could not be found or the user does not have access to the folder. | ClientError |
409 | Returns an error when a policy for this folder and template is already in place. * `tuple_already_exists` - A cascade policy for this combination of `folder_id`, `scope` and `templateKey` already exists. | ConflictError |
default | An unexpected client error. | ClientError |
GET/metadata_cascade_policies/{metadata_cascade_policy_id}Get metadata cascade policy
Parameters
| Name | In | Required | Type |
|---|---|---|---|
metadata_cascade_policy_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a metadata cascade policy. | MetadataCascadePolicy |
404 | Returns an error when the policy can not be found or the user does not have access to the folder. * `instance_not_found` - The policy could not be found * `not_found` - The folder could not be found or the user does not have access to the folder. | ClientError |
default | An unexpected client error. | ClientError |
DELETE/metadata_cascade_policies/{metadata_cascade_policy_id}Remove metadata cascade policy
Parameters
| Name | In | Required | Type |
|---|---|---|---|
metadata_cascade_policy_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Returns an empty response when the policy is successfully deleted. | — |
404 | Returns an error when the policy can not be found or the user does not have access to the folder. * `instance_not_found` - The policy could not be found * `not_found` - The folder could not be found or the user does not have access to the folder. | ClientError |
default | An unexpected client error. | ClientError |
POST/metadata_cascade_policies/{metadata_cascade_policy_id}/applyForce-apply metadata cascade policy to folder
Parameters
| Name | In | Required | Type |
|---|---|---|---|
metadata_cascade_policy_id | path | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
202 | Returns an empty response when the API call was successful. The metadata cascade operation will be performed asynchronously. The API call will return directly, before the cascade operation is complete. There is currently no API to check for the status of this operation. | — |
404 | Returns an error when the policy can not be found or the user does not have access to the folder. * `instance_not_found` - The policy could not be found * `not_found` - The folder could not be found or the user does not have access to the folder. | ClientError |
default | An unexpected client error. | ClientError |
Metadata instances (Files)5
A metadata instance describes the relation between a template and a file, including the values that are assigned for every field.
GET/files/{file_id}/metadataList metadata instances on file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
view | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns all the metadata associated with a file. This API does not support pagination and will therefore always return all of the metadata associated to the file. | Metadatas |
403 | Returned when the request parameters are not valid. | ClientError |
404 | Returned when the user does not have access to the file. | ClientError |
default | An unexpected client error. | ClientError |
GET/files/{file_id}/metadata/{scope}/{template_key}Get metadata instance on file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
scope | path | yes | string |
template_key | path | yes | string |
view | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
201 | An instance of the metadata template that includes additional "key:value" pairs defined by the user or an application. | Metadata--Full |
400 | Returned when the request parameters are not valid. | ClientError |
404 | Returned if the metadata template specified was not applied to this file or the user does not have access to the file. * `instance_not_found` - The metadata template was not applied to the file. | ClientError |
405 | Returned when the method was not allowed. | ClientError |
default | An unexpected client error. | ClientError |
POST/files/{file_id}/metadata/{scope}/{template_key}Create metadata instance on file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
scope | path | yes | string |
template_key | path | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns the instance of the template that was applied to the file, including the data that was applied to the template. | Metadata--Full |
400 | Returns an error when the request body is not valid. * `schema_validation_failed` - The request body contains a value for a field that either does not exist, or for which the value or type does not match the expected field type. An example might be an unknown option for an `enum` or `multiSelect` field. | MetadataError |
404 | Returns an error when the file or metadata template was not found. * `not_found` - The file could not be found, or the user does not have access to the file. * `instance_tuple_not_found` - The metadata template was not found. | ClientError |
409 | Returns an error when an instance of this metadata template is already present on the file. * `tuple_already_exists` - An instance of the metadata template already exists on the file. | MetadataError |
default | An unexpected client error. | ClientError |
PUT/files/{file_id}/metadata/{scope}/{template_key}Update metadata instance on file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
scope | path | yes | string |
template_key | path | yes | string |
Request body
application/json-patch+json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the updated metadata template instance, with the custom template data included. | Metadata--Full |
400 | Returns an error when the request body is not valid. * `bad_request` - The request body format is not an array of valid JSON Patch objects. | ClientError |
500 | Returns an error in some edge cases when the request body is not a valid array of JSON Patch items. | ClientError |
default | An unexpected client error. | ClientError |
DELETE/files/{file_id}/metadata/{scope}/{template_key}Remove metadata instance from file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
scope | path | yes | string |
template_key | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Returns an empty response when the metadata is successfully deleted. | — |
400 | Returned when the request parameters are not valid. This may happen of the `scope` is not valid. | ClientError |
404 | Returns an error when the file does not have an instance of the metadata template applied to it, or when the user does not have access to the file. * `instance_not_found` - An instance of the metadata template with the given `scope` and `templateKey` was not found on this file. * `not_found` - The file was not found, or the user does not have access to the file. | ClientError |
405 | Returned when the method was not allowed. | ClientError |
default | An unexpected client error. | ClientError |
Metadata instances (Folders)5
A metadata instance describes the relation between a template and a folder, including the values that are assigned for every field.
GET/folders/{folder_id}/metadataList metadata instances on folder
Parameters
| Name | In | Required | Type |
|---|---|---|---|
folder_id | path | yes | string |
view | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns all the metadata associated with a folder. This API does not support pagination and will therefore always return all of the metadata associated to the folder. | Metadatas |
403 | Returned when the request parameters are not valid. * `forbidden` - this operation is not allowed on the Root folder. | ClientError |
404 | Returned when the user does not have access to the folder. | ClientError |
default | An unexpected client error. | ClientError |
GET/folders/{folder_id}/metadata/{scope}/{template_key}Get metadata instance on folder
Parameters
| Name | In | Required | Type |
|---|---|---|---|
folder_id | path | yes | string |
scope | path | yes | string |
template_key | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
201 | An instance of the metadata template that includes additional "key:value" pairs defined by the user or an application. | Metadata--Full |
403 | Returned when the request parameters are not valid. | ClientError |
404 | Returned if the metadata template specified was not applied to this folder or the user does not have access to the folder. * `instance_not_found` - The metadata template was not applied to the folder. | ClientError |
405 | Returned when the method was not allowed. This often happens when the folder ID is not valid or the root folder with ID `0`. | ClientError |
default | An unexpected client error. | ClientError |
POST/folders/{folder_id}/metadata/{scope}/{template_key}Create metadata instance on folder
Parameters
| Name | In | Required | Type |
|---|---|---|---|
folder_id | path | yes | string |
scope | path | yes | string |
template_key | path | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns the instance of the template that was applied to the folder, including the data that was applied to the template. | Metadata--Full |
400 | Returns an error when the request body is not valid. * `schema_validation_failed` - The request body contains a value for a field that either does not exist, or for which the value or type does not match the expected field type. An example might be an unknown option for an `enum` or `multiSelect` field. | MetadataError |
404 | Returns an error when the folder or metadata template was not found. * `not_found` - The folder could not be found, or the user does not have access to the folder. * `instance_tuple_not_found` - The metadata template was not found. | ClientError |
409 | Returns an error when an instance of this metadata template is already present on the folder. * `tuple_already_exists` - An instance of the metadata template already exists on the folder. | MetadataError |
default | An unexpected client error. | ClientError |
PUT/folders/{folder_id}/metadata/{scope}/{template_key}Update metadata instance on folder
Parameters
| Name | In | Required | Type |
|---|---|---|---|
folder_id | path | yes | string |
scope | path | yes | string |
template_key | path | yes | string |
Request body
application/json-patch+json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the updated metadata template instance, with the custom template data included. | Metadata--Full |
400 | Returns an error when the request body is not valid. * `bad_request` - The request body format is not an array of valid JSON Patch objects. | ClientError |
500 | Returns an error in some edge cases when the request body is not a valid array of JSON Patch items. | ClientError |
default | An unexpected client error. | ClientError |
DELETE/folders/{folder_id}/metadata/{scope}/{template_key}Remove metadata instance from folder
Parameters
| Name | In | Required | Type |
|---|---|---|---|
folder_id | path | yes | string |
scope | path | yes | string |
template_key | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Returns an empty response when the metadata is successfully deleted. | — |
400 | Returned when the request parameters are not valid. This may happen of the `scope` is not valid. | ClientError |
404 | Returns an error when the folder does not have an instance of the metadata template applied to it, or when the user does not have access to the folder. * `instance_not_found` - An instance of the metadata template with the given `scope` and `templateKey` was not found on this folder. * `not_found` - The folder was not found, or the user does not have access to the folder. | ClientError |
405 | Returned when the method was not allowed. This often happens when the folder ID is not valid or the root folder with ID `0`. | ClientError |
default | An unexpected client error. | ClientError |
Metadata taxonomies15
A metadata taxonomy is a hierarchical classification system that helps organize and manage metadata within an enterprise.
POST/metadata_taxonomiesCreate metadata taxonomy
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | The schema representing the metadata taxonomy created. | MetadataTaxonomy |
400 | Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. In many cases this response will include extra details on what fields are missing. | ClientError |
403 | Returned when the user does not have the permission to create the metadata taxonomy. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have access to the provided namespace. | ClientError |
default | An unexpected client error. | ClientError |
GET/metadata_taxonomies/{namespace}Get metadata taxonomies for namespace
Parameters
| Name | In | Required | Type |
|---|---|---|---|
namespace | path | yes | string |
marker | query | no | string |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns all of the metadata taxonomies within a namespace and their corresponding schema. | MetadataTaxonomies |
400 | Returned when the request parameters are not valid. | ClientError |
default | An unexpected client error. | ClientError |
GET/metadata_taxonomies/{namespace}/{taxonomy_key}Get metadata taxonomy by taxonomy key
Parameters
| Name | In | Required | Type |
|---|---|---|---|
namespace | path | yes | string |
taxonomy_key | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the metadata taxonomy identified by the taxonomy key. | MetadataTaxonomy |
400 | Returned when the request parameters are not valid. | ClientError |
404 | Returned when a taxonomy with the given `namespace` and `taxonomy_key` cannot be found. | ClientError |
default | An unexpected client error. | ClientError |
PATCH/metadata_taxonomies/{namespace}/{taxonomy_key}Update metadata taxonomy
Parameters
| Name | In | Required | Type |
|---|---|---|---|
namespace | path | yes | string |
taxonomy_key | path | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | The schema representing the updated metadata taxonomy. | MetadataTaxonomy |
400 | Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. In many cases this response will include extra details on what fields are missing. | ClientError |
403 | Returned when the user does not have the permission to modify the metadata taxonomy. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have access to the provided namespace. | ClientError |
default | An unexpected client error. | ClientError |
DELETE/metadata_taxonomies/{namespace}/{taxonomy_key}Remove metadata taxonomy
Parameters
| Name | In | Required | Type |
|---|---|---|---|
namespace | path | yes | string |
taxonomy_key | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Returns an empty response when the metadata taxonomy is successfully deleted. | — |
400 | Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. In many cases this response will include extra details on what fields are missing. | ClientError |
403 | Returned when the user does not have the permission to delete the metadata taxonomy. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have access to the provided namespace. | ClientError |
404 | Returned if the metadata taxonomy does not exist. | ClientError |
default | An unexpected client error. | ClientError |
POST/metadata_taxonomies/{namespace}/{taxonomy_key}/levelsCreate metadata taxonomy levels
Parameters
| Name | In | Required | Type |
|---|---|---|---|
namespace | path | yes | string |
taxonomy_key | path | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns an array of all taxonomy levels. | MetadataTaxonomyLevels |
400 | Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. In many cases this response will include extra details on what fields are missing. | ClientError |
403 | Returned when the user does not have the permission to modify the metadata taxonomy. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have access to the provided namespace. | ClientError |
default | An unexpected client error. | ClientError |
PATCH/metadata_taxonomies/{namespace}/{taxonomy_key}/levels/{level_index}Update metadata taxonomy level
Parameters
| Name | In | Required | Type |
|---|---|---|---|
namespace | path | yes | string |
taxonomy_key | path | yes | string |
level_index | path | yes | integer |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | The updated taxonomy level. | MetadataTaxonomyLevel |
400 | Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. In many cases this response will include extra details on what fields are missing. | ClientError |
403 | Returned when the user does not have the permission to modify the metadata taxonomy. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have access to the provided namespace. | ClientError |
default | An unexpected client error. | ClientError |
POST/metadata_taxonomies/{namespace}/{taxonomy_key}/levels:appendAdd metadata taxonomy level
Parameters
| Name | In | Required | Type |
|---|---|---|---|
namespace | path | yes | string |
taxonomy_key | path | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns an array of all taxonomy levels. | MetadataTaxonomyLevels |
400 | Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. In many cases this response will include extra details on what fields are missing. | ClientError |
403 | Returned when the user does not have the permission to modify the metadata taxonomy. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have access to the provided namespace. | ClientError |
default | An unexpected client error. | ClientError |
POST/metadata_taxonomies/{namespace}/{taxonomy_key}/levels:trimDelete metadata taxonomy level
Parameters
| Name | In | Required | Type |
|---|---|---|---|
namespace | path | yes | string |
taxonomy_key | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns an array of all taxonomy levels. | MetadataTaxonomyLevels |
400 | Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. In many cases this response will include extra details on what fields are missing. | ClientError |
403 | Returned when the user does not have the permission to modify the metadata taxonomy. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have access to the provided namespace. | ClientError |
default | An unexpected client error. | ClientError |
GET/metadata_taxonomies/{namespace}/{taxonomy_key}/nodesList metadata taxonomy nodes
Parameters
| Name | In | Required | Type |
|---|---|---|---|
namespace | path | yes | string |
taxonomy_key | path | yes | string |
level | query | no | array |
parent | query | no | array |
ancestor | query | no | array |
query | query | no | string |
include-total-result-count | query | no | boolean |
marker | query | no | string |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a list of the taxonomy nodes that match the specified parameters. | MetadataTaxonomyNodes |
400 | Returned when the request parameters are not valid. | ClientError |
default | An unexpected client error. | ClientError |
POST/metadata_taxonomies/{namespace}/{taxonomy_key}/nodesCreate metadata taxonomy node
Parameters
| Name | In | Required | Type |
|---|---|---|---|
namespace | path | yes | string |
taxonomy_key | path | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | The schema representing the taxonomy node created. | MetadataTaxonomyNode |
400 | Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. In many cases this response will include extra details on what fields are missing. | ClientError |
403 | Returned when the user does not have the permission to modify the metadata taxonomy. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have access to the provided namespace. | ClientError |
default | An unexpected client error. | ClientError |
GET/metadata_taxonomies/{namespace}/{taxonomy_key}/nodes/{node_id}Get metadata taxonomy node by ID
Parameters
| Name | In | Required | Type |
|---|---|---|---|
namespace | path | yes | string |
taxonomy_key | path | yes | string |
node_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the metadata taxonomy node that matches the identifier. | MetadataTaxonomyNode |
400 | Returned if any of the request parameters are not valid. | ClientError |
404 | Returned if the taxonomy node with the given `node_id` cannot be found. | ClientError |
default | An unexpected client error. | ClientError |
PATCH/metadata_taxonomies/{namespace}/{taxonomy_key}/nodes/{node_id}Update metadata taxonomy node
Parameters
| Name | In | Required | Type |
|---|---|---|---|
namespace | path | yes | string |
taxonomy_key | path | yes | string |
node_id | path | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | The schema representing the updated taxonomy node. | MetadataTaxonomyNode |
400 | Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. In many cases this response will include extra details on what fields are missing. | ClientError |
403 | Returned when the user does not have the permission to modify the metadata taxonomy. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have access to the provided namespace. | ClientError |
default | An unexpected client error. | ClientError |
DELETE/metadata_taxonomies/{namespace}/{taxonomy_key}/nodes/{node_id}Remove metadata taxonomy node
Parameters
| Name | In | Required | Type |
|---|---|---|---|
namespace | path | yes | string |
taxonomy_key | path | yes | string |
node_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Returns an empty response when the metadata taxonomy node is successfully deleted. | — |
400 | Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. In many cases this response will include extra details on what fields are missing. | ClientError |
403 | Returned when the user does not have the permission to delete the metadata taxonomy node. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the user doesn't have access to the provided namespace. | ClientError |
404 | Returned if the metadata taxonomy node does not exist. | ClientError |
default | An unexpected client error. | ClientError |
GET/metadata_templates/{namespace}/{template_key}/fields/{field_key}/optionsList metadata template's options for taxonomy field
Parameters
| Name | In | Required | Type |
|---|---|---|---|
namespace | path | yes | string |
template_key | path | yes | string |
field_key | path | yes | string |
level | query | no | array |
parent | query | no | array |
ancestor | query | no | array |
query | query | no | string |
include-total-result-count | query | no | boolean |
only-selectable-options | query | no | boolean |
marker | query | no | string |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a list of the taxonomy nodes that match the specified parameters. | MetadataTaxonomyNodes |
400 | Returned when the request parameters are not valid. | ClientError |
default | An unexpected client error. | ClientError |
Metadata templates8
A metadata template describes a reusable set of key/value pairs that can be assigned to a file.
GET/metadata_templatesFind metadata template by instance ID
Parameters
| Name | In | Required | Type |
|---|---|---|---|
metadata_instance_id | query | yes | string |
marker | query | no | string |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a list containing the 1 metadata template that matches the instance ID. | MetadataTemplates |
400 | Returned when the request parameters are not valid. | ClientError |
default | An unexpected client error. | ClientError |
GET/metadata_templates/enterpriseList all metadata templates for enterprise
Parameters
| Name | In | Required | Type |
|---|---|---|---|
marker | query | no | string |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns all of the metadata templates within an enterprise and their corresponding schema. | MetadataTemplates |
400 | Returned when the request parameters are not valid. | ClientError |
default | An unexpected client error. | ClientError |
GET/metadata_templates/globalList all global metadata templates
Parameters
| Name | In | Required | Type |
|---|---|---|---|
marker | query | no | string |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns all of the metadata templates available to all enterprises and their corresponding schema. | MetadataTemplates |
400 | Returned when the request parameters are not valid. | ClientError |
default | An unexpected client error. | ClientError |
POST/metadata_templates/schemaCreate metadata template
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | The schema representing the metadata template created. | MetadataTemplate |
400 | Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. In many cases this response will include extra details on what fields are missing. | ClientError |
403 | Returned when the user does not have the permission to create the metadata template. This can happen for a few reasons, most commonly when the user does not have (co-)admin permissions, or the application tries to create a template with the `global` scope. | ClientError |
default | An unexpected client error. | ClientError |
GET/metadata_templates/{scope}/{template_key}/schemaGet metadata template by name
Parameters
| Name | In | Required | Type |
|---|---|---|---|
scope | path | yes | string |
template_key | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the metadata template matching the `scope` and `template` name. | MetadataTemplate |
400 | Returned if any of the request parameters are not valid. * `bad_request`: Often returned when the scope of the template is not recognised. Please make sure to use either `enterprise` or `global` as the `scope` value. | ClientError |
404 | Returned when a template with the given `scope` and `template_key` can not be found. | ClientError |
default | An unexpected client error. | ClientError |
PUT/metadata_templates/{scope}/{template_key}/schemaUpdate metadata template
Parameters
| Name | In | Required | Type |
|---|---|---|---|
scope | path | yes | string |
template_key | path | yes | string |
Request body
application/json-patch+json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the updated metadata template, with the custom template data included. | MetadataTemplate |
400 | The request body does not contain a valid metadata schema. | ClientError |
403 | The request body contains a scope that the user is not allowed to create templates for. | ClientError |
404 | The requested template could not be found. | ClientError |
default | An unexpected client error. | ClientError |
DELETE/metadata_templates/{scope}/{template_key}/schemaRemove metadata template
Parameters
| Name | In | Required | Type |
|---|---|---|---|
scope | path | yes | string |
template_key | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Returns an empty response when the metadata template is successfully deleted. | — |
400 | Request body does not contain a valid metadata schema. | ClientError |
403 | Request body contains a scope that the user is not allowed to create a template for. | ClientError |
default | An unexpected client error. | ClientError |
GET/metadata_templates/{template_id}Get metadata template by ID
Parameters
| Name | In | Required | Type |
|---|---|---|---|
template_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the metadata template that matches the ID. | MetadataTemplate |
400 | Returned if any of the request parameters are not valid. * `bad_request`: Often returned with a message when the ID of the template is not recognised. | MetadataTemplate |
default | An unexpected client error. | ClientError |
Recent items1
Recent items represent items such as files or folders that the user accessed recently.
GET/recent_itemsList recently accessed items
Parameters
| Name | In | Required | Type |
|---|---|---|---|
fields | query | no | array |
limit | query | no | integer |
marker | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a list recent items access by a user. | RecentItems |
default | An unexpected client error. | ClientError |
Retention policies5
A retention policy blocks permanent deletion of content for a specified amount of time. Admins can create retention policies and then assign them to specific folders or their entire enterprise.
GET/retention_policiesList retention policies
Parameters
| Name | In | Required | Type |
|---|---|---|---|
policy_name | query | no | string |
policy_type | query | no | string |
created_by_user_id | query | no | string |
fields | query | no | array |
limit | query | no | integer |
marker | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a list retention policies in the enterprise. | RetentionPolicies |
400 | Returns a `bad_request` if a non existent `policy_type` was specified. | ClientError |
404 | Returns a `not_found` error if the user specified in `created_by_user_id` does not exist. | ClientError |
default | An unexpected client error. | ClientError |
POST/retention_policiesCreate retention policy
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns a new retention policy object. | RetentionPolicy |
400 | Returns a `bad_request` error when the `retention_length` was specified for an `indefinite` retention policy, an incorrect `disposition_action` was set, `max_extension_length` is not allowed for the given policy type or disposition action, or description exceeds maximum length of 500 characters. | ClientError |
409 | Returns an error if a retention policy with the given name already exists. | ClientError |
default | An unexpected client error. | ClientError |
GET/retention_policies/{retention_policy_id}Get retention policy
Parameters
| Name | In | Required | Type |
|---|---|---|---|
retention_policy_id | path | yes | string |
fields | query | no | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the retention policy object. | RetentionPolicy |
default | An unexpected client error. | ClientError |
PUT/retention_policies/{retention_policy_id}Update retention policy
Parameters
| Name | In | Required | Type |
|---|---|---|---|
retention_policy_id | path | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the updated retention policy object. | RetentionPolicy |
400 | Returns a `bad_request` if an incorrect `disposition_action` was set, `max_extension_length` is not allowed for the given policy type or disposition action, or description exceeds maximum length of 500 characters. | ClientError |
403 | Returns an error when a user wants to shorten the duration of a non-modifiable policy, or to convert a non-modifiable policy to a modifiable one. Note: Lengthening policy duration is allowed. | ClientError |
409 | Returns an error if a retention policy with the given name already exists. | ClientError |
default | An unexpected client error. | ClientError |
DELETE/retention_policies/{retention_policy_id}Delete retention policy
Parameters
| Name | In | Required | Type |
|---|---|---|---|
retention_policy_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Returns an empty response when the policy has been deleted. | — |
403 | Returns an error if the policy is non-modifiable or the user does not have the required access to perform the action. | ClientError |
404 | Returns an error if the policy is not found. | ClientError |
default | An unexpected client error. | ClientError |
Retention policy assignments6
A Retention Policy Assignment is a relation between a policy and folder or enterprise. Creating an assignment puts a retention on all the file versions that belong to that folder or enterprise.
GET/retention_policies/{retention_policy_id}/assignmentsList retention policy assignments
Parameters
| Name | In | Required | Type |
|---|---|---|---|
retention_policy_id | path | yes | string |
type | query | no | string |
fields | query | no | array |
marker | query | no | string |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a list of the retention policy assignments associated with the specified retention policy. | RetentionPolicyAssignments |
400 | Returns an error if an unknown `type` is specified. | ClientError |
default | An unexpected client error. | ClientError |
POST/retention_policy_assignmentsAssign retention policy
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns a new retention policy assignment object. | RetentionPolicyAssignment |
400 | Returns an error if an `id` is specified while assigning the retention policy to an enterprise. Returns an error if `start_date_field` is present but `assign_to.type` is not `metadata_template` Returns an error if `start_date_field` is present, but belongs to a different metadata template than the one specified in `assign_to.id` Returns an error if `start_date_field` is present, but the `retention_policy` has a `retention_length` of "indefinite" Returns an error if `start_date_field` is present, but cannot be resolved to a valid metadata date field. | ClientError |
404 | Returns an error if no retention policy with the given `policy_id` exists. | ClientError |
409 | Returns an error if a retention policy of equal or greater length has already been assigned to this item. | ClientError |
default | An unexpected client error. | ClientError |
GET/retention_policy_assignments/{retention_policy_assignment_id}Get retention policy assignment
Parameters
| Name | In | Required | Type |
|---|---|---|---|
retention_policy_assignment_id | path | yes | string |
fields | query | no | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the retention policy assignment object. | RetentionPolicyAssignment |
default | An unexpected client error. | ClientError |
DELETE/retention_policy_assignments/{retention_policy_assignment_id}Remove retention policy assignment
Parameters
| Name | In | Required | Type |
|---|---|---|---|
retention_policy_assignment_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Returns an empty response when the policy assignment is successfully deleted. | — |
403 | Returns an error when the assignment relates to a retention policy that cannot be modified. | ClientError |
404 | Returns an error when the retention policy assignment does not exist. | ClientError |
default | An unexpected client error. | ClientError |
GET/retention_policy_assignments/{retention_policy_assignment_id}/file_versions_under_retentionGet file versions under retention
Parameters
| Name | In | Required | Type |
|---|---|---|---|
retention_policy_assignment_id | path | yes | string |
marker | query | no | string |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a list of file versions under retention that are associated with the specified retention policy assignment. | FilesUnderRetention |
400 | Returns an error if `retention_policy_assignment_id` is not specified. | ClientError |
default | An unexpected client error. | ClientError |
GET/retention_policy_assignments/{retention_policy_assignment_id}/files_under_retentionGet files under retention
Parameters
| Name | In | Required | Type |
|---|---|---|---|
retention_policy_assignment_id | path | yes | string |
marker | query | no | string |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a list of files under retention that are associated with the specified retention policy assignment. | FilesUnderRetention |
400 | Returns an error if `retention_policy_assignment_id` is not specified. | ClientError |
default | An unexpected client error. | ClientError |
Search2
The Box API provides a way to find content in Box using full-text search queries.
POST/metadata_queries/execute_readQuery files/folders by metadata
Request body
application/json — MetadataQuery
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a list of files and folders that match this metadata query. | MetadataQueryResults |
400 | Returns an error when the request body is not valid. * `invalid_query` - Any of the provided body parameters might be incorrect. This can mean the `query` is incorrect, as well as some cases where the `from` value does not represent a valid template. * `unexpected_json_type` - An argument from the `query` string is not present in `query_param`. For example, `query` of `name = :name` requires the `query_param` to include a value for the `name` argument, for example `{ "name": "Box, Inc" }`. | ClientError |
404 | Returns an error when a metadata template with the given `scope` and `templateKey` can not be found. The error response will include extra details. * `instance_not_found` - The template was not found. Please make sure to use the full template scope including the enterprise ID, like `enterprise_12345`. | ClientError |
default | An unexpected client error. | ClientError |
GET/searchSearch for content
Parameters
| Name | In | Required | Type |
|---|---|---|---|
query | query | no | string |
scope | query | no | string |
file_extensions | query | no | array |
created_at_range | query | no | array |
updated_at_range | query | no | array |
size_range | query | no | array |
owner_user_ids | query | no | array |
recent_updater_user_ids | query | no | array |
ancestor_folder_ids | query | no | array |
content_types | query | no | array |
type | query | no | string |
trash_content | query | no | string |
mdfilters | query | no | array |
sort | query | no | string |
direction | query | no | string |
limit | query | no | integer |
include_recent_shared_links | query | no | boolean |
fields | query | no | array |
offset | query | no | integer |
deleted_user_ids | query | no | array |
deleted_at_range | query | no | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a collection of search results. If there are no matching search results, the `entries` array will be empty. | SearchResultsResponse |
400 | Returns an error when the request was not valid. This can have multiple reasons and the `context_info` object will provide you with more details. * `missing_parameter` - Please provide at least the `query` or `mdfilters` query parameter in a search. * `invalid_parameter` - Any of the fields might not be in the right format. This could for example mean that one of the RFC3339 dates is incorrect, or a string is provided where an integer is expected. | ClientError |
403 | Returns an error when the user does not have the permission to make this API call. * The developer provided a `scope` of `enterprise_content` but did not request this scope to be enabled for the user through our support channels. | ClientError |
404 | Returns an error when the user does not have access to an item mentioned in the request. * The developer provided a folder ID in `ancestor_folder_ids` that either does not exist or the user does not have access to. | ClientError |
default | An unexpected client error. | ClientError |
Session termination2
Session termination API is used to validate the roles and permissions of the group, and creates asynchronous jobs to terminate the group's sessions.
POST/groups/terminate_sessionsCreate jobs to terminate user group session
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
202 | Returns a message about the request status. | SessionTerminationMessage |
400 | Returns an error if some of the parameters are not valid. * `Groups can not be NULL or EMPTY` when no value is provided. * `group id format is string` when the provided group id format is incorrect. * `Supported payload format is JSON` when the provided payload format is incorrect. | ClientError |
403 | Returns an error if there are insufficient permissions. | ClientError |
404 | Returns an error if the resource could not be found. | ClientError |
429 | Returns an error if the request limit is exceeded. | ClientError |
500 | Returns an error if there is an internal server issue. | ClientError |
503 | Returns an error if the request timed out. | ClientError |
default | An unexpected client error. | ClientError |
POST/users/terminate_sessionsCreate jobs to terminate users session
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
202 | Returns a message about the request status. | SessionTerminationMessage |
400 | Returns an error if some of the parameters are not valid. * `Users can not be NULL or EMPTY` when no value is provided. * `User id format is string` when the provided user id format is incorrect. * `Supported payload format is JSON` when the provided payload format is incorrect. | ClientError |
403 | Returns an error if there are insufficient permissions. | ClientError |
404 | Returns an error if the resource could not be found. | ClientError |
429 | Returns an error if the rate limit is exceeded. | ClientError |
500 | Returns an error if there is an internal server issue. | ClientError |
503 | Returns an error if the request timed out. | ClientError |
default | An unexpected client error. | ClientError |
Shared links (Files)5
Files shared links are URLs that are generated for files stored in Box, which provide direct, read-only access to the resource.
PUT/files/{file_id}#add_shared_linkAdd shared link to file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
fields | query | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the base representation of a file with a new shared link attached. | File--Full |
400 | Returned when there is an incorrect permission combination. | ClientError |
401 | Returned when the access token provided in the `Authorization` header is not recognized or not provided. | ClientError |
403 | Returned if the user does not have all the permissions to complete the update. | ClientError |
404 | Returned if the file is not found, or the user does not have access to the file. | ClientError |
405 | Returned if the `file_id` is not in a recognized format. | ClientError |
412 | Returns an error when the `If-Match` header does not match the current `etag` value of the file. This indicates that the file has changed since it was last requested. | ClientError |
default | An unexpected client error. | ClientError |
GET/files/{file_id}#get_shared_linkGet shared link for file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
fields | query | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the base representation of a file with the additional shared link information. | File--Full |
401 | Returned when the access token provided in the `Authorization` header is not recognized or not provided. | ClientError |
404 | Returned if the file is not found, or the user does not have access to the file. | ClientError |
405 | Returned if the `file_id` is not in a recognized format. | ClientError |
default | An unexpected client error. | ClientError |
PUT/files/{file_id}#remove_shared_linkRemove shared link from file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
fields | query | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a basic representation of a file, with the shared link removed. | File--Full |
401 | Returned when the access token provided in the `Authorization` header is not recognized or not provided. | ClientError |
403 | Returned if the user does not have all the permissions to complete the update. | ClientError |
404 | Returned if the file is not found, or the user does not have access to the file. | ClientError |
405 | Returned if the `file_id` is not in a recognized format. | ClientError |
412 | Returns an error when the `If-Match` header does not match the current `etag` value of the file. This indicates that the file has changed since it was last requested. | ClientError |
default | An unexpected client error. | ClientError |
PUT/files/{file_id}#update_shared_linkUpdate shared link on file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
fields | query | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a basic representation of the file, with the updated shared link attached. | File--Full |
400 | Returned when there is an incorrect permission combination. | ClientError |
401 | Returned when the access token provided in the `Authorization` header is not recognized or not provided. | ClientError |
403 | Returned if the user does not have all the permissions to complete the update. | ClientError |
404 | Returned if the file is not found, or the user does not have access to the file. | ClientError |
405 | Returned if the `file_id` is not in a recognized format. | ClientError |
412 | Returns an error when the `If-Match` header does not match the current `etag` value of the file. This indicates that the file has changed since it was last requested. | ClientError |
default | An unexpected client error. | ClientError |
GET/shared_itemsFind file for shared link
Parameters
| Name | In | Required | Type |
|---|---|---|---|
if-none-match | header | no | string |
fields | query | no | array |
boxapi | header | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a full file resource if the shared link is valid and the user has access to it. | File--Full |
304 | Returns an empty response when the `If-None-Match` header matches the current `etag` value of the file. This indicates that the file has not changed since it was last requested. | — |
default | An unexpected client error. | ClientError |
Shared links (Folders)5
Folders shared links are URLs that are generated for folders stored in Box, which provide direct, read-only access to the resource.
PUT/folders/{folder_id}#add_shared_linkAdd shared link to folder
Parameters
| Name | In | Required | Type |
|---|---|---|---|
folder_id | path | yes | string |
fields | query | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the base representation of a folder with a new shared link attached. | Folder--Full |
400 | Returned when there is an incorrect permission combination. | ClientError |
401 | Returned when the access token provided in the `Authorization` header is not recognized or not provided. | ClientError |
403 | Returned if the user does not have all the permissions to complete the update. | ClientError |
404 | Returned if the folder is not found, or the user does not have access to the folder. | ClientError |
405 | Returned if the `folder_id` is not in a recognized format. | ClientError |
412 | Returns an error when the `If-Match` header does not match the current `etag` value of the folder. This indicates that the folder has changed since it was last requested. | ClientError |
default | An unexpected client error. | ClientError |
GET/folders/{folder_id}#get_shared_linkGet shared link for folder
Parameters
| Name | In | Required | Type |
|---|---|---|---|
folder_id | path | yes | string |
fields | query | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the base representation of a folder with the additional shared link information. | Folder--Full |
401 | Returned when the access token provided in the `Authorization` header is not recognized or not provided. | ClientError |
404 | Returned if the folder is not found, or the user does not have access to the folder. | ClientError |
405 | Returned if the `folder_id` is not in a recognized format. | ClientError |
default | An unexpected client error. | ClientError |
PUT/folders/{folder_id}#remove_shared_linkRemove shared link from folder
Parameters
| Name | In | Required | Type |
|---|---|---|---|
folder_id | path | yes | string |
fields | query | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a basic representation of a folder, with the shared link removed. | Folder--Full |
401 | Returned when the access token provided in the `Authorization` header is not recognized or not provided. | ClientError |
403 | Returned if the user does not have all the permissions to complete the update. | ClientError |
404 | Returned if the folder is not found, or the user does not have access to the folder. | ClientError |
405 | Returned if the `folder_id` is not in a recognized format. | ClientError |
412 | Returns an error when the `If-Match` header does not match the current `etag` value of the folder. This indicates that the folder has changed since it was last requested. | ClientError |
default | An unexpected client error. | ClientError |
PUT/folders/{folder_id}#update_shared_linkUpdate shared link on folder
Parameters
| Name | In | Required | Type |
|---|---|---|---|
folder_id | path | yes | string |
fields | query | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a basic representation of the folder, with the updated shared link attached. | Folder--Full |
400 | Returned when there is an incorrect permission combination. | ClientError |
401 | Returned when the access token provided in the `Authorization` header is not recognized or not provided. | ClientError |
403 | Returned if the user does not have all the permissions to complete the update. | ClientError |
404 | Returned if the folder is not found, or the user does not have access to the folder. | ClientError |
405 | Returned if the `folder_id` is not in a recognized format. | ClientError |
412 | Returns an error when the `If-Match` header does not match the current `etag` value of the folder. This indicates that the folder has changed since it was last requested. | ClientError |
default | An unexpected client error. | ClientError |
GET/shared_items#foldersFind folder for shared link
Parameters
| Name | In | Required | Type |
|---|---|---|---|
if-none-match | header | no | string |
fields | query | no | array |
boxapi | header | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a full folder resource if the shared link is valid and the user has access to it. | Folder--Full |
304 | Returns an empty response when the `If-None-Match` header matches the current `etag` value of the folder. This indicates that the folder has not changed since it was last requested. | — |
default | An unexpected client error. | ClientError |
Shared links (Web Links)5
Web links for files are URLs that are generated for web links in Box, which provide direct, read-only access to the resource.
GET/shared_items#web_linksFind web link for shared link
Parameters
| Name | In | Required | Type |
|---|---|---|---|
if-none-match | header | no | string |
fields | query | no | array |
boxapi | header | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a full web link resource if the shared link is valid and the user has access to it. | WebLink |
304 | Returns an empty response when the `If-None-Match` header matches the current `etag` value of the web link. This indicates that the web link has not changed since it was last requested. | — |
default | An unexpected client error. | ClientError |
PUT/web_links/{web_link_id}#add_shared_linkAdd shared link to web link
Parameters
| Name | In | Required | Type |
|---|---|---|---|
web_link_id | path | yes | string |
fields | query | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the base representation of a web link with a new shared link attached. | WebLink |
400 | Returned when there is an incorrect permission combination. | ClientError |
401 | Returned when the access token provided in the `Authorization` header is not recognized or not provided. | ClientError |
403 | Returned if the user does not have all the permissions to complete the update. | ClientError |
404 | Returned if the file is not found, or the user does not have access to the file. | ClientError |
405 | Returned if the `file_id` is not in a recognized format. | ClientError |
412 | Returns an error when the `If-Match` header does not match the current `etag` value of the file. This indicates that the file has changed since it was last requested. | ClientError |
default | An unexpected client error. | ClientError |
GET/web_links/{web_link_id}#get_shared_linkGet shared link for web link
Parameters
| Name | In | Required | Type |
|---|---|---|---|
web_link_id | path | yes | string |
fields | query | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the base representation of a web link with the additional shared link information. | WebLink |
401 | Returned when the access token provided in the `Authorization` header is not recognized or not provided. | ClientError |
404 | Returned if the file is not found, or the user does not have access to the file. | ClientError |
405 | Returned if the `file_id` is not in a recognized format. | ClientError |
default | An unexpected client error. | ClientError |
PUT/web_links/{web_link_id}#remove_shared_linkRemove shared link from web link
Parameters
| Name | In | Required | Type |
|---|---|---|---|
web_link_id | path | yes | string |
fields | query | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a basic representation of a web link, with the shared link removed. | WebLink |
401 | Returned when the access token provided in the `Authorization` header is not recognized or not provided. | ClientError |
403 | Returned if the user does not have all the permissions to complete the update. | ClientError |
404 | Returned if the file is not found, or the user does not have access to the file. | ClientError |
405 | Returned if the `file_id` is not in a recognized format. | ClientError |
412 | Returns an error when the `If-Match` header does not match the current `etag` value of the file. This indicates that the file has changed since it was last requested. | ClientError |
default | An unexpected client error. | ClientError |
PUT/web_links/{web_link_id}#update_shared_linkUpdate shared link on web link
Parameters
| Name | In | Required | Type |
|---|---|---|---|
web_link_id | path | yes | string |
fields | query | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a basic representation of the web link, with the updated shared link attached. | WebLink |
400 | Returned when there is an incorrect permission combination. | ClientError |
401 | Returned when the access token provided in the `Authorization` header is not recognized or not provided. | ClientError |
403 | Returned if the user does not have all the permissions to complete the update. | ClientError |
404 | Returned if the file is not found, or the user does not have access to the file. | ClientError |
405 | Returned if the `file_id` is not in a recognized format. | ClientError |
412 | Returns an error when the `If-Match` header does not match the current `etag` value of the file. This indicates that the file has changed since it was last requested. | ClientError |
default | An unexpected client error. | ClientError |
Shared links (App Items)1
URLs generated for app items stored in Box, which provide direct, read-only access to the resource.
GET/shared_items#app_itemsFind app item for shared link
Parameters
| Name | In | Required | Type |
|---|---|---|---|
boxapi | header | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a full app item resource if the shared link is valid and the user has access to it. | AppItem |
default | An unexpected client error. | ClientError |
Shield information barriers4
Shield information barrier in Box defines an ethical wall. An ethical wall is a mechanism that prevents exchanges or communication that could lead to conflicts of interest and therefore result in business activities ethically or legally questionable.
GET/shield_information_barriersList shield information barriers
Parameters
| Name | In | Required | Type |
|---|---|---|---|
marker | query | no | string |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a paginated list of shield information barrier objects, empty list if currently no barrier. | ShieldInformationBarriers |
404 | Returns a `not_found` error if could not find an enterprise using JWT. | ClientError |
default | An unexpected client error. | ClientError |
POST/shield_information_barriersCreate shield information barrier
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns a new shield information barrier object. | ShieldInformationBarrier |
400 | Returns an error if the enterprise is missing from the request. | ClientError |
404 | Returns an error when an incorrect or null enterprise is present in the request body. | ClientError |
default | An unexpected client error. | ClientError |
POST/shield_information_barriers/change_statusAdd changed status of shield information barrier with specified ID
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the updated shield information barrier object. | ShieldInformationBarrier |
404 | Returns a `not_found` error if the shield information barrier was not found. | ClientError |
409 | Returns an error if there exists Conflicts with existing information barriers. | ClientError |
default | An unexpected client error. | ClientError |
GET/shield_information_barriers/{shield_information_barrier_id}Get shield information barrier with specified ID
Parameters
| Name | In | Required | Type |
|---|---|---|---|
shield_information_barrier_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the shield information barrier object. | ShieldInformationBarrier |
404 | Returns a `not_found` error if the shield information barrier was not found. | ClientError |
default | An unexpected client error. | ClientError |
Shield information barrier segments5
Shield information barrier segment represents a defined group of users. A user can be a member of only one segment, which makes segments different from groups.
GET/shield_information_barrier_segmentsList shield information barrier segments
Parameters
| Name | In | Required | Type |
|---|---|---|---|
shield_information_barrier_id | query | yes | string |
marker | query | no | string |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a paginated list of shield information barrier segment objects. | ShieldInformationBarrierSegments |
404 | Returns a `not_found` error if the shield information Barrier of given ID was not found. | ClientError |
default | An unexpected client error. | ClientError |
POST/shield_information_barrier_segmentsCreate shield information barrier segment
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns a new shield information barrier segment object. | ShieldInformationBarrierSegment |
404 | Returns an error if the shield information barrier was not found. | ClientError |
409 | Returns an error if there exists an shield information barrier segment with same name. | ClientError |
default | An unexpected client error. | ClientError |
GET/shield_information_barrier_segments/{shield_information_barrier_segment_id}Get shield information barrier segment with specified ID
Parameters
| Name | In | Required | Type |
|---|---|---|---|
shield_information_barrier_segment_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the shield information barrier segment object. | ShieldInformationBarrierSegment |
404 | Returns a `not_found` error if the shield information barrier segment was not found. | ClientError |
default | An unexpected client error. | ClientError |
PUT/shield_information_barrier_segments/{shield_information_barrier_segment_id}Update shield information barrier segment with specified ID
Parameters
| Name | In | Required | Type |
|---|---|---|---|
shield_information_barrier_segment_id | path | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the updated shield information barrier segment object. | ShieldInformationBarrierSegment |
404 | Returns a `not_found` error if the shield information Barrier Segment was not found. | ClientError |
409 | Returns an error if there exists a shield information Barrier Segment with the same name. | ClientError |
default | An unexpected client error. | ClientError |
DELETE/shield_information_barrier_segments/{shield_information_barrier_segment_id}Delete shield information barrier segment
Parameters
| Name | In | Required | Type |
|---|---|---|---|
shield_information_barrier_segment_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Empty body in response. | — |
404 | Returns a `not_found` error if the shield information barrier segment with specified ID was not found. | ClientError |
default | An unexpected client error. | ClientError |
Shield information barrier segment members4
Shield information barrier segment member represents a user that is assigned to a specific segment.
GET/shield_information_barrier_segment_membersList shield information barrier segment members
Parameters
| Name | In | Required | Type |
|---|---|---|---|
shield_information_barrier_segment_id | query | yes | string |
marker | query | no | string |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a paginated list of shield information barrier segment member objects. | ShieldInformationBarrierSegmentMembers |
default | An unexpected client error. | ClientError |
POST/shield_information_barrier_segment_membersCreate shield information barrier segment member
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns a new shield information barrier segment member object. | ShieldInformationBarrierSegmentMember |
404 | Returns an error if the shield information barrier or segment was not found. | ClientError |
default | An unexpected client error. | ClientError |
GET/shield_information_barrier_segment_members/{shield_information_barrier_segment_member_id}Get shield information barrier segment member by ID
Parameters
| Name | In | Required | Type |
|---|---|---|---|
shield_information_barrier_segment_member_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the shield information barrier segment member object. | ShieldInformationBarrierSegmentMember |
404 | Returns a `not_found` error if the shield information barrier segment member was not found. | ClientError |
default | An unexpected client error. | ClientError |
DELETE/shield_information_barrier_segment_members/{shield_information_barrier_segment_member_id}Delete shield information barrier segment member by ID
Parameters
| Name | In | Required | Type |
|---|---|---|---|
shield_information_barrier_segment_member_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Returns an empty response if the segment member was deleted successfully. | — |
404 | Returns a `not_found` error if the shield information barrier segment member was not found. | ClientError |
default | An unexpected client error. | ClientError |
Shield information barrier reports3
Shield information barrier reports contain information on what existing collaborations will be removed permanently when the information barrier is enabled.
GET/shield_information_barrier_reportsList shield information barrier reports
Parameters
| Name | In | Required | Type |
|---|---|---|---|
shield_information_barrier_id | query | yes | string |
marker | query | no | string |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a paginated list of shield information barrier report objects. | ShieldInformationBarrierReports |
404 | Returns a `not_found` error if the Shield Information Barrier could not be found. | ClientError |
default | An unexpected client error. | ClientError |
POST/shield_information_barrier_reportsCreate shield information barrier report
Request body
application/json — ShieldInformationBarrierReference
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns the shield information barrier report information object. | ShieldInformationBarrierReport |
404 | Returns a `not_found` error if the shield information barrier report was not found. | ClientError |
409 | Returns a `conflict` error if a shield information barrier report is currently being created. | ClientError |
default | An unexpected client error. | ClientError |
GET/shield_information_barrier_reports/{shield_information_barrier_report_id}Get shield information barrier report by ID
Parameters
| Name | In | Required | Type |
|---|---|---|---|
shield_information_barrier_report_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the shield information barrier report object. | ShieldInformationBarrierReport |
404 | Returns a `not_found` error if the shield information barrier Report was not found. | ClientError |
default | An unexpected client error. | ClientError |
Shield information barrier segment restrictions4
Shield information barrier segment restriction is an access restriction based on the content (file or folder) owner.
GET/shield_information_barrier_segment_restrictionsList shield information barrier segment restrictions
Parameters
| Name | In | Required | Type |
|---|---|---|---|
shield_information_barrier_segment_id | query | yes | string |
marker | query | no | string |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a paginated list of shield information barrier segment restriction objects. | ShieldInformationBarrierSegmentRestrictions |
default | An unexpected client error. | ClientError |
POST/shield_information_barrier_segment_restrictionsCreate shield information barrier segment restriction
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns the newly created Shield Information Barrier Segment Restriction object. | ShieldInformationBarrierSegmentRestriction |
404 | Returns a `not_found` error if the shield information barrier or segment was not found. | ClientError |
default | An unexpected client error. | ClientError |
GET/shield_information_barrier_segment_restrictions/{shield_information_barrier_segment_restriction_id}Get shield information barrier segment restriction by ID
Parameters
| Name | In | Required | Type |
|---|---|---|---|
shield_information_barrier_segment_restriction_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the shield information barrier segment restriction object. | ShieldInformationBarrierSegmentRestriction |
404 | Returns a `not_found` error if the shield information barrier segment restriction was not found. | ClientError |
default | An unexpected client error. | ClientError |
DELETE/shield_information_barrier_segment_restrictions/{shield_information_barrier_segment_restriction_id}Delete shield information barrier segment restriction by ID
Parameters
| Name | In | Required | Type |
|---|---|---|---|
shield_information_barrier_segment_restriction_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Empty body in response. | — |
404 | Returns a `not_found` error if the shield information barrier segment restriction was not found. | ClientError |
default | An unexpected client error. | ClientError |
Box Sign templates2
Sign templates allow you to use a predefined Box Sign template when creating a signature request. The template includes placeholders that are automatically populated with data when creating the request.
GET/sign_templatesList Box Sign templates
Parameters
| Name | In | Required | Type |
|---|---|---|---|
marker | query | no | string |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a collection of templates. | SignTemplates |
401 | Returned when the access token provided in the `Authorization` header is not recognized or not provided. | ClientError |
default | An unexpected client error. | ClientError |
GET/sign_templates/{template_id}Get Box Sign template by ID
Parameters
| Name | In | Required | Type |
|---|---|---|---|
template_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns details of a template. | SignTemplate |
401 | Returned when the access token provided in the `Authorization` header is not recognized or not provided. | ClientError |
404 | Returned if the template is not found or the user does not have access to the associated template. | ClientError |
default | An unexpected client error. | ClientError |
Skills5
Box Skills are designed to allow custom processing of files uploaded to Box, with the intent of enhancing the underlying metadata of the file.
GET/files/{file_id}/metadata/global/boxSkillsCardsList Box Skill cards on file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns all the metadata associated with a file. This API does not support pagination and will therefore always return all of the metadata associated to the file. | SkillCardsMetadata |
default | An unexpected client error. | ClientError |
POST/files/{file_id}/metadata/global/boxSkillsCardsCreate Box Skill cards on file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns the instance of the template that was applied to the file, including the data that was applied to the template. | SkillCardsMetadata |
400 | Returns an error when the request body is not valid. * `schema_validation_failed` - The request body contains a value for a field that either does not exist, or for which the value or type does not match the expected field type. An example might be an unknown option for an `enum` or `multiSelect` field. | ClientError |
404 | Returns an error when the file or metadata template was not found. * `not_found` - The file could not be found, or the user does not have access to the file. * `instance_tuple_not_found` - The metadata template was not found. | ClientError |
409 | Returns an error when an instance of this metadata template is already present on the file. * `tuple_already_exists` - An instance of them metadata template already exists on the file. | ClientError |
default | An unexpected client error. | ClientError |
PUT/files/{file_id}/metadata/global/boxSkillsCardsUpdate Box Skill cards on file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
Request body
application/json-patch+json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the updated metadata template, with the custom template data included. | SkillCardsMetadata |
404 | The requested file could not be found. | ClientError |
default | An unexpected client error. | ClientError |
DELETE/files/{file_id}/metadata/global/boxSkillsCardsRemove Box Skill cards from file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Returns an empty response when the cards are successfully deleted. | — |
404 | Returns an error when the file does not have an instance of the Box Skill cards applied to it, or when the user does not have access to the file. * `instance_not_found` - An instance of the metadata template for Box Skill cards was not found on this file. * `not_found` - The file was not found, or the user does not have access to the file. | ClientError |
405 | Returned when the method was not allowed. | ClientError |
default | An unexpected client error. | ClientError |
PUT/skill_invocations/{skill_id}Update all Box Skill cards on file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
skill_id | path | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns an empty response when the card has been successfully updated. | — |
400 | Returns an error when the request body is not valid. * `schema_validation_failed` - The request body contains a value for a field that either does not exist, or for which the value or type does not match the expected field type. An example might be an unknown option for an `enum` or `multiSelect` field. | ClientError |
404 | Returns an error when the file could not be found or the user does not have access. * `not_found` - The file could not be found, or the user does not have access to the file. | ClientError |
default | An unexpected client error. | ClientError |
Standard and Zones Storage Policies2
Storage policy assignment represents the storage zone for items in a given enterprise.
GET/storage_policiesList storage policies
Parameters
| Name | In | Required | Type |
|---|---|---|---|
fields | query | no | array |
marker | query | no | string |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a collection of storage policies. | StoragePolicies |
default | An unexpected client error. | ClientError |
GET/storage_policies/{storage_policy_id}Get storage policy
Parameters
| Name | In | Required | Type |
|---|---|---|---|
storage_policy_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a storage policy object. | StoragePolicy |
default | An unexpected client error. | ClientError |
Standard and Zones Storage Policy Assignments5
Storage policy assignment represents the relation between storage zone and the assigned item (for example a file stored in a specific zone).
GET/storage_policy_assignmentsList storage policy assignments
Parameters
| Name | In | Required | Type |
|---|---|---|---|
marker | query | no | string |
resolved_for_type | query | yes | string |
resolved_for_id | query | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a collection of storage policies for the enterprise or user. | StoragePolicyAssignments |
default | An unexpected client error. | ClientError |
POST/storage_policy_assignmentsAssign storage policy
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the new storage policy assignment created. | StoragePolicyAssignment |
default | An unexpected client error. | ClientError |
GET/storage_policy_assignments/{storage_policy_assignment_id}Get storage policy assignment
Parameters
| Name | In | Required | Type |
|---|---|---|---|
storage_policy_assignment_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a storage policy assignment object. | StoragePolicyAssignment |
default | An unexpected client error. | ClientError |
PUT/storage_policy_assignments/{storage_policy_assignment_id}Update storage policy assignment
Parameters
| Name | In | Required | Type |
|---|---|---|---|
storage_policy_assignment_id | path | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns an updated storage policy assignment object. | StoragePolicyAssignment |
default | An unexpected client error. | ClientError |
DELETE/storage_policy_assignments/{storage_policy_assignment_id}Unassign storage policy
Parameters
| Name | In | Required | Type |
|---|---|---|---|
storage_policy_assignment_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Returns an empty response when the storage policy assignment is successfully deleted. | — |
default | An unexpected client error. | ClientError |
Task assignments5
A task assignment defines which task is assigned to which user to complete.
POST/task_assignmentsAssign task
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns a new task assignment object. | TaskAssignment |
403 | Returns an error if a change is attempted for a completed task or the user does not have access to the item linked to the task for the given task assignment. | ClientError |
404 | Returns an error when the task cannot be found. | ClientError |
500 | Returns an error if any of the IDs for this request were not valid, or if the targeted user does not have access to the file. | ClientError |
default | An unexpected client error. | ClientError |
GET/task_assignments/{task_assignment_id}Get task assignment
Parameters
| Name | In | Required | Type |
|---|---|---|---|
task_assignment_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a task assignment, specifying who the task has been assigned to and by whom. | TaskAssignment |
404 | Returns an error when the task assignment could not be found or the user does not have access to the file the task is assigned to. | ClientError |
default | An unexpected client error. | ClientError |
PUT/task_assignments/{task_assignment_id}Update task assignment
Parameters
| Name | In | Required | Type |
|---|---|---|---|
task_assignment_id | path | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the updated task assignment object. | TaskAssignment |
400 | Returns an error if a resolution state is incompatible with the action type of the task. | ClientError |
404 | Returns an error when the task assignment could not be found or the user does not have access to the file the task is assigned to. | ClientError |
default | An unexpected client error. | ClientError |
DELETE/task_assignments/{task_assignment_id}Unassign task
Parameters
| Name | In | Required | Type |
|---|---|---|---|
task_assignment_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Returns an empty response when the task assignment was successfully deleted. | — |
404 | Returns an error if the task assignment for the given ID does not exist or is inaccessible to your account. | ClientError |
default | An unexpected client error. | ClientError |
GET/tasks/{task_id}/assignmentsList task assignments
Parameters
| Name | In | Required | Type |
|---|---|---|---|
task_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a collection of task assignment defining what task on a file has been assigned to which users and by who. | TaskAssignments |
404 | Returns an error when the task could not be found or the user does not have access to the file the task is assigned to. | ClientError |
500 | Returns an error if the task assignment ID was omitted in the request. | ClientError |
default | An unexpected client error. | ClientError |
Tasks5
Tasks allow users to request collaborators on a file to review a file or complete a piece of work. Tasks can be used by developers to create file-centric workflows.
GET/files/{file_id}/tasksList tasks on file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a list of tasks on a file. If there are no tasks on this file an empty collection is returned instead. | Tasks |
404 | Returns an error when the file could not be found or the user does not have access to the file. | ClientError |
405 | Returns an error when the `file_id` was not provided. | ClientError |
500 | Returns an error when an attempt was made to retrieve tasks for the file with ID `0`. | ClientError |
default | An unexpected client error. | ClientError |
POST/tasksCreate task
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns the newly created task. | Task |
400 | Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. This may be because the `action` or `completion_rule` are not one of the allowed values. | ClientError |
403 | Returns an error when the user does not have the permission to create a task on the file. | ClientError |
404 | Returns an error when the file could not be found or the user does not have access to the file. | ClientError |
default | An unexpected client error. | ClientError |
GET/tasks/{task_id}Get task
Parameters
| Name | In | Required | Type |
|---|---|---|---|
task_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a task object. | Task |
404 | Returns an error when the task could not be found or the user does not have access to the file the task is assigned to. | ClientError |
default | An unexpected client error. | ClientError |
PUT/tasks/{task_id}Update task
Parameters
| Name | In | Required | Type |
|---|---|---|---|
task_id | path | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the updated task object. | Task |
400 | Returned if the request parameters or body is not valid. * `bad_request` when the body does not contain a valid request. This may be because the `action` or `completion_rule` are not one of the allowed values. | ClientError |
403 | Returns an error when the user does not have the permission to update a task on the file. | ClientError |
404 | Returns an error when the file could not be found or the user does not have access to the file. | ClientError |
default | An unexpected client error. | ClientError |
DELETE/tasks/{task_id}Remove task
Parameters
| Name | In | Required | Type |
|---|---|---|---|
task_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Returns an empty response when the task was successfully deleted. | — |
404 | Returns an error when the task could not be found or the user does not have access to the file the task is assigned to. | ClientError |
default | An unexpected client error. | ClientError |
Terms of service4
A set of endpoints used to manage terms of service agreements.
GET/terms_of_servicesList terms of services
Parameters
| Name | In | Required | Type |
|---|---|---|---|
tos_type | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a collection of terms of service text and settings for the enterprise. | TermsOfServices |
default | An unexpected client error. | ClientError |
POST/terms_of_servicesCreate terms of service
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a new task object. | TermsOfService |
default | An unexpected client error. | ClientError |
GET/terms_of_services/{terms_of_service_id}Get terms of service
Parameters
| Name | In | Required | Type |
|---|---|---|---|
terms_of_service_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a terms of service object. | TermsOfService |
default | An unexpected client error. | ClientError |
PUT/terms_of_services/{terms_of_service_id}Update terms of service
Parameters
| Name | In | Required | Type |
|---|---|---|---|
terms_of_service_id | path | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns an updated terms of service object. | TermsOfService |
default | An unexpected client error. | ClientError |
Terms of service user statuses3
A set of endpoints used to manage the status of terms of service for a particular user.
GET/terms_of_service_user_statusesList terms of service user statuses
Parameters
| Name | In | Required | Type |
|---|---|---|---|
tos_id | query | yes | string |
user_id | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a list of terms of service statuses. | TermsOfServiceUserStatuses |
default | An unexpected client error. | ClientError |
POST/terms_of_service_user_statusesCreate terms of service status for new user
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns a terms of service status object. | TermsOfServiceUserStatus |
default | An unexpected client error. | ClientError |
PUT/terms_of_service_user_statuses/{terms_of_service_user_status_id}Update terms of service status for existing user
Parameters
| Name | In | Required | Type |
|---|---|---|---|
terms_of_service_user_status_id | path | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the updated terms of service status object. | TermsOfServiceUserStatus |
default | An unexpected client error. | ClientError |
Transfer folders1
API designed to move all of the items (files, folders and workflows) owned by a user into another user's account.
PUT/users/{user_id}/folders/0Transfer owned folders
Parameters
| Name | In | Required | Type |
|---|---|---|---|
user_id | path | yes | string |
fields | query | no | array |
notify | query | no | boolean |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the information for the newly created destination folder. | Folder--Full |
403 | Returns an error when folder ownership cannot be transferred to another user. * `forbidden_by_policy`: Returned if ownership transfer is forbidden due to information barrier restrictions. * `Cannot transfer files from/to higher privileged accounts`: You can only transfer content to or from managed users or your own account, not other co-admins or admins. Admins can transfer content between any users, including co-admins and managed users. | ClientError |
default | An unexpected client error. | ClientError |
Trashed files3
Files that were deleted and are in trash.
POST/files/{file_id}Restore file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
fields | query | no | array |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns a file object when the file has been restored. | TrashFileRestored |
403 | Returns an error if the user does not have access to the folder the file is being restored to, or the user does not have permission to restore files from the trash. | ClientError |
404 | Returns an error if the file is not in the trash. | ClientError |
409 | Returns an error if there is an file with the same name in the folder the file is being restored to. | ClientError |
default | An unexpected client error. | ClientError |
GET/files/{file_id}/trashGet trashed file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
fields | query | no | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the file that was trashed, including information about when the it was moved to the trash. | TrashFile |
404 | Returns an error if the file can not be found directly in the trash. Please note that a `HTTP 404` is also returned if any of the file's parent folders have been moved to the trash. In that case, only that parent folder can be inspected using the [`GET /folders/:id/trash`](https://developer.box.com/reference/get-folders-id-trash) API. | ClientError |
default | An unexpected client error. | ClientError |
DELETE/files/{file_id}/trashPermanently remove file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Returns an empty response when the file was permanently deleted. | — |
404 | Returns an error if the file is not in the trash. | ClientError |
default | An unexpected client error. | ClientError |
Trashed folders3
Folders that were deleted and are in trash.
POST/folders/{folder_id}Restore folder
Parameters
| Name | In | Required | Type |
|---|---|---|---|
folder_id | path | yes | string |
fields | query | no | array |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns a folder object when the folder has been restored. | TrashFolderRestored |
403 | Returns an error if the user does not have access to the folder the folder is being restored to, or the user does not have permission to restore folders from the trash. | ClientError |
404 | Returns an error if the folder is not in the trash. | ClientError |
409 | Returned an error if there is a folder with the same name in the destination folder. `operation_blocked_temporary`: Returned if either of the destination or source folders is locked due to another move, copy, delete or restore operation in process. The operation can be retried at a later point. | ClientError |
default | An unexpected client error. | ClientError |
GET/folders/{folder_id}/trashGet trashed folder
Parameters
| Name | In | Required | Type |
|---|---|---|---|
folder_id | path | yes | string |
fields | query | no | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the folder that was trashed, including information about when the it was moved to the trash. | TrashFolder |
404 | Returns an error if the folder can not be found directly in the trash. Please note that a `HTTP 404` is also returned if any of the folder's parent folders have been moved to the trash. In that case, only that parent folder can be inspected using the [`GET /folders/:id/trash`](https://developer.box.com/reference/get-folders-id-trash) API. | ClientError |
default | An unexpected client error. | ClientError |
DELETE/folders/{folder_id}/trashPermanently remove folder
Parameters
| Name | In | Required | Type |
|---|---|---|---|
folder_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Returns an empty response when the folder was permanently deleted. | — |
404 | Returns an error if the folder is not in the trash. | ClientError |
default | An unexpected client error. | ClientError |
Trashed items1
Items that were deleted and are in trash.
GET/folders/trash/itemsList trashed items
Parameters
| Name | In | Required | Type |
|---|---|---|---|
fields | query | no | array |
limit | query | no | integer |
offset | query | no | integer |
usemarker | query | no | boolean |
marker | query | no | string |
direction | query | no | string |
sort | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a list of items that have been deleted. | Items |
400 | Returns an error if some of the parameters are missing or not valid. * `invalid_parameter` can appear when the `sort`, `direction` or `offset` parameter is provided when using marker based pagination, or when the `marker` parameter is provided but `usemarker` is set to `false` or `null`. | ClientError |
default | An unexpected client error. | ClientError |
Trashed web links3
Web links that were deleted and are in trash.
POST/web_links/{web_link_id}Restore web link
Parameters
| Name | In | Required | Type |
|---|---|---|---|
web_link_id | path | yes | string |
fields | query | no | array |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns a web link object when it has been restored. | TrashWebLinkRestored |
403 | Returns an error if the user does not have access to the folder the web link is being restored to, or the user does not have permission to restore web link from the trash. | ClientError |
404 | Returns an error if the web link is not in the trash. | ClientError |
409 | Returns an error if there is an web link with the same name in the folder the web link is being restored to. | ClientError |
default | An unexpected client error. | ClientError |
GET/web_links/{web_link_id}/trashGet trashed web link
Parameters
| Name | In | Required | Type |
|---|---|---|---|
web_link_id | path | yes | string |
fields | query | no | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the web link that was trashed, including information about when the it was moved to the trash. | TrashWebLink |
404 | Returns an error if the web link is not in the trash. | ClientError |
default | An unexpected client error. | ClientError |
DELETE/web_links/{web_link_id}/trashPermanently remove web link
Parameters
| Name | In | Required | Type |
|---|---|---|---|
web_link_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Returns an empty response when the web link was permanently deleted. | — |
404 | Returns an error if the web link is not in the trash. | ClientError |
default | An unexpected client error. | ClientError |
Uploads2
The direct file upload API supports files up to 50MB in size and sends all the binary data to the Box API in 1 API request.
POST/files/contentUpload file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
fields | query | no | array |
content-md5 | header | no | string |
Request body
multipart/form-data
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns the new file object in a list. | Files |
400 | Returns an error if some of the parameters are missing or not valid. * `bad_request` when a parameter is missing or incorrect. * `item_name_too_long` when the folder name is too long. * `item_name_invalid` when the folder name contains non-valid characters. | ClientError |
404 | Returns an error if the parent folder does not exist or if the user is not authorized to access the parent folder. | ClientError |
409 | Returns an error if the file already exists, or the account has run out of disk space. | ClientError |
default | An unexpected client error. | ClientError |
POST/files/{file_id}/contentUpload file version
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
if-match | header | no | string |
fields | query | no | array |
content-md5 | header | no | string |
Request body
multipart/form-data
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the new file object in a list. | Files |
412 | Returns an error when the `If-Match` header does not match the current `etag` value of the file. This indicates that the file has changed since it was last requested. | ClientError |
default | An unexpected client error. | ClientError |
Uploads (Chunked)7
The chunked upload endpoints support files from 20MB in size and allow an application to upload the file in parts, allowing for more control to catch any errors and retry parts individually.
POST/files/upload_sessionsCreate upload session
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns a new upload session. | UploadSession |
400 | Returns an error if some of the parameters are missing or not valid. * `missing_destination`: No `folder_id` was provided. * `invalid_folder_id`: `folder_id` is not valid. * `item_name_invalid`: `file_name` is not valid. * `missing_file_size`: `file_size` was not provided. * `invalid_file_size`: `file_size` was not a valid number. * `file_size_too_small`: `file_size` is below minimum file size for uploads via this API. * `missing_file_name`: `file_name` was not provided. | ClientError |
403 | Returns an error if the operation is not allowed for some reason. * `storage_limit_exceeded`: Account storage limit reached. | ClientError |
404 | Returns an error if the parent folder could not be found, or the authenticated user does not have access to it. * `invalid_parameter`: The `folder_id` value represents a folder that the user does not have access to, or does not exist. | ClientError |
409 | Returns an error if the file already exists, or the account has run out of disk space. | ClientError |
default | An unexpected client error. | ClientError |
GET/files/upload_sessions/{upload_session_id}Get upload session
Parameters
| Name | In | Required | Type |
|---|---|---|---|
upload_session_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns an upload session object. | UploadSession |
default | An unexpected client error. | ClientError |
PUT/files/upload_sessions/{upload_session_id}Upload part of file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
upload_session_id | path | yes | string |
digest | header | yes | string |
content-range | header | yes | string |
Request body
application/octet-stream
Responses
| Status | Description | Schema |
|---|---|---|
200 | Chunk has been uploaded successfully. | UploadedPart |
409 | Returns an error if the chunk conflicts with another chunk previously uploaded. | ClientError |
412 | Returns an error if a precondition was not met. | ClientError |
416 | Returns an error if the content range does not match a specified range for the session. | ClientError |
default | An unexpected client error. | ClientError |
DELETE/files/upload_sessions/{upload_session_id}Remove upload session
Parameters
| Name | In | Required | Type |
|---|---|---|---|
upload_session_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | A blank response is returned if the session was successfully aborted. | — |
default | An unexpected client error. | ClientError |
POST/files/upload_sessions/{upload_session_id}/commitCommit upload session
Parameters
| Name | In | Required | Type |
|---|---|---|---|
upload_session_id | path | yes | string |
digest | header | yes | string |
if-match | header | no | string |
if-none-match | header | no | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns the file object in a list. | Files |
202 | Returns when all chunks have been uploaded but not yet processed. Inspect the upload session to get more information about the progress of processing the chunks, then retry committing the file when all chunks have processed. | — |
409 | Returns an error if there is already a file with the same name in the target folder. | ClientError |
412 | Returns an error if the `If-Match` or `If-None-Match` conditions fail. | ClientError |
default | An unexpected client error. | ClientError |
GET/files/upload_sessions/{upload_session_id}/partsList parts
Parameters
| Name | In | Required | Type |
|---|---|---|---|
upload_session_id | path | yes | string |
offset | query | no | integer |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a list of parts that have been uploaded. | UploadParts |
default | An unexpected client error. | ClientError |
POST/files/{file_id}/upload_sessionsCreate upload session for existing file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns a new upload session. | UploadSession |
409 | Returns an error if the file already exists, or if the account has run out of disk space. | ClientError |
default | An unexpected client error. | ClientError |
User avatars3
User avatars are JPG or PNG files uploaded to Box to represent the user image. They are then displayed in the user account.
GET/users/{user_id}/avatarGet user avatar
Parameters
| Name | In | Required | Type |
|---|---|---|---|
user_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | When an avatar can be found for the user the image data will be returned in the body of the response. | — |
default | An unexpected client error. | ClientError |
POST/users/{user_id}/avatarAdd or update user avatar
Parameters
| Name | In | Required | Type |
|---|---|---|---|
user_id | path | yes | string |
Request body
multipart/form-data
Responses
| Status | Description | Schema |
|---|---|---|
200 | `ok`: Returns the `pic_urls` object with URLs to existing user avatars that were updated. | UserAvatar |
201 | `created`: Returns the `pic_urls` object with URLS to user avatars uploaded to Box with the request. | UserAvatar |
400 | `bad_request`: Returns an error when: * An image is not included in the request * The uploaded file is empty * The image size exceeds 1024 * 1024 pixels or 1MB * The file extension is other than `.jpg` or `.png`. | ClientError |
403 | `forbidden`: Returns an error if the user does not have permissions necessary to upload an avatar or is not activated. | ClientError |
404 | `not_found`: Returns an error if the user does not exist or cannot be found. | ClientError |
default | An unexpected client error. | ClientError |
DELETE/users/{user_id}/avatarDelete user avatar
Parameters
| Name | In | Required | Type |
|---|---|---|---|
user_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | `no_content`: Removes the avatar and returns an empty response. | — |
403 | `forbidden`: Returned if the user does not have necessary permissions or is not activated. | ClientError |
404 | `not_found`: Returned if the user or user avatar does not exist or cannot be found. | ClientError |
default | An unexpected client error. | ClientError |
Users6
Box API supports a variety of users, ranging from real employees logging in with their Managed User account, to applications using App Users to drive powerful automation workflows.
GET/usersList enterprise users
Parameters
| Name | In | Required | Type |
|---|---|---|---|
filter_term | query | no | string |
user_type | query | no | string |
external_app_user_id | query | no | string |
fields | query | no | array |
offset | query | no | integer |
limit | query | no | integer |
usemarker | query | no | boolean |
marker | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns all of the users in the enterprise. | Users |
default | An unexpected client error. | ClientError |
POST/usersCreate user
Parameters
| Name | In | Required | Type |
|---|---|---|---|
fields | query | no | array |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns a user object for the newly created user. | User--Full |
default | An unexpected client error. | ClientError |
GET/users/meGet current user
Parameters
| Name | In | Required | Type |
|---|---|---|---|
fields | query | no | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a single user object. | User--Full |
default | An unexpected client error. | ClientError |
GET/users/{user_id}Get user
Parameters
| Name | In | Required | Type |
|---|---|---|---|
user_id | path | yes | string |
fields | query | no | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a single user object. Not all available fields are returned by default. Use the [fields](#parameter-fields) query parameter to explicitly request any specific fields using the [fields](#parameter-fields) parameter. | User--Full |
default | An unexpected client error. | ClientError |
PUT/users/{user_id}Update user
Parameters
| Name | In | Required | Type |
|---|---|---|---|
user_id | path | yes | string |
fields | query | no | array |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the updated user object. | User--Full |
400 | Returns an error if some of the parameters are missing or not valid. * `invalid_parameter` when a parameter is formatted incorrectly, for example when the `notification_email` has an incorrectly formatted email address. | ClientError |
403 | Returns an error if the user is not allowed to make the changes. * `access_denied_insufficient_permissions` when the user does not have the right permissions, for example when updating the notification email is turned off for the enterprise. * `denied_by_policy` when the user does not have the right permissions due to the information barrier restrictions. | ClientError |
default | An unexpected client error. | ClientError |
DELETE/users/{user_id}Delete user
Parameters
| Name | In | Required | Type |
|---|---|---|---|
user_id | path | yes | string |
notify | query | no | boolean |
force | query | no | boolean |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Removes the user and returns an empty response. | — |
default | An unexpected client error. | ClientError |
Watermarks (Files)3
A watermark is a semi-transparent overlay on an embedded file preview that displays a viewer's email address or user ID and the time of access over the file.
GET/files/{file_id}/watermarkGet watermark on file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns an object containing information about the watermark associated for to this file. | Watermark |
404 | Returns an error if the file does not have a watermark applied. | ClientError |
default | An unexpected client error. | ClientError |
PUT/files/{file_id}/watermarkApply watermark to file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns an updated watermark if a watermark already existed on this file. | Watermark |
201 | Returns a new watermark if no watermark existed on this file yet. | Watermark |
default | An unexpected client error. | ClientError |
DELETE/files/{file_id}/watermarkRemove watermark from file
Parameters
| Name | In | Required | Type |
|---|---|---|---|
file_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Removes the watermark and returns an empty response. | — |
404 | Returns an error if the file did not have a watermark applied to it. | ClientError |
default | An unexpected client error. | ClientError |
Watermarks (Folders)3
A watermark is a semi-transparent overlay on an embedded folder preview that displays a viewer's email address or user ID and the time of access over the folder content.
GET/folders/{folder_id}/watermarkGet watermark for folder
Parameters
| Name | In | Required | Type |
|---|---|---|---|
folder_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns an object containing information about the watermark associated for to this folder. | Watermark |
404 | Returns an error if the folder does not have a watermark applied. | ClientError |
default | An unexpected client error. | ClientError |
PUT/folders/{folder_id}/watermarkApply watermark to folder
Parameters
| Name | In | Required | Type |
|---|---|---|---|
folder_id | path | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns an updated watermark if a watermark already existed on this folder. | Watermark |
201 | Returns a new watermark if no watermark existed on this folder yet. | Watermark |
default | An unexpected client error. | ClientError |
DELETE/folders/{folder_id}/watermarkRemove watermark from folder
Parameters
| Name | In | Required | Type |
|---|---|---|---|
folder_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | An empty response will be returned when the watermark was successfully deleted. | — |
404 | Returns an error if the folder did not have a watermark applied to it. | ClientError |
default | An unexpected client error. | ClientError |
Web links4
Web links are objects that point to URLs. These objects are also known as bookmarks within the Box web application.
POST/web_linksCreate web link
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the newly created web link object. | WebLink |
default | An unexpected client error. | ClientError |
GET/web_links/{web_link_id}Get web link
Parameters
| Name | In | Required | Type |
|---|---|---|---|
web_link_id | path | yes | string |
boxapi | header | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the web link object. | WebLink |
default | An unexpected client error. | ClientError |
PUT/web_links/{web_link_id}Update web link
Parameters
| Name | In | Required | Type |
|---|---|---|---|
web_link_id | path | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the updated web link object. | WebLink |
default | An unexpected client error. | ClientError |
DELETE/web_links/{web_link_id}Remove web link
Parameters
| Name | In | Required | Type |
|---|---|---|---|
web_link_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | An empty response will be returned when the web link was successfully deleted. | — |
default | An unexpected client error. | ClientError |
Webhooks5
Webhooks allow you to monitor Box content for events, and receive notifications to a URL of your choice when they occur. For example, a workflow may include waiting for a file to be downloaded to delete a shared link.
GET/webhooksList all webhooks
Parameters
| Name | In | Required | Type |
|---|---|---|---|
marker | query | no | string |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a list of webhooks. | Webhooks |
403 | Returns an error if the application does not have the permission to manage webhooks. | ClientError |
default | An unexpected client error. | ClientError |
POST/webhooksCreate webhook
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
201 | Returns the new webhook object. | Webhook |
400 | Returns an error if the parameters were incorrect. | ClientError |
403 | Returns an error if the application does not have the permission to manage webhooks. | ClientError |
404 | Returns an error if the target item could not be found. | ClientError |
409 | Returns an error if the a webhook for this combination of target, application, and user already exists. | ClientError |
default | An unexpected client error. | ClientError |
GET/webhooks/{webhook_id}Get webhook
Parameters
| Name | In | Required | Type |
|---|---|---|---|
webhook_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns a webhook object. | Webhook |
403 | Returns an error if the application does not have the permission to manage webhooks. | ClientError |
404 | Returns an error if the webhook could not be found. | ClientError |
default | An unexpected client error. | ClientError |
PUT/webhooks/{webhook_id}Update webhook
Parameters
| Name | In | Required | Type |
|---|---|---|---|
webhook_id | path | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the new webhook object. | Webhook |
400 | Returns an error if the parameters were incorrect. | ClientError |
403 | Returns an error if the application does not have the permission to manage webhooks. | ClientError |
404 | Returns an error if the target item or webhook could not be found. | ClientError |
409 | Returns an error if the a webhook for this combination of target, application, and user already exists. | ClientError |
default | An unexpected client error. | ClientError |
DELETE/webhooks/{webhook_id}Remove webhook
Parameters
| Name | In | Required | Type |
|---|---|---|---|
webhook_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | An empty response will be returned when the webhook was successfully deleted. | — |
403 | Returns an error if the application does not have the permission to manage webhooks. | ClientError |
404 | Returns an error if the webhook could not be found. | ClientError |
default | An unexpected client error. | ClientError |
Workflows2
Box Relay Workflows are objects that represent a named collection of flows.
GET/workflowsList workflows
Parameters
| Name | In | Required | Type |
|---|---|---|---|
folder_id | query | yes | string |
trigger_type | query | no | string |
limit | query | no | integer |
marker | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the workflow. | Workflows |
400 | Returned if the trigger type is not `WORKFLOW_MANUAL_START`. | ClientError |
404 | Returned if the folder is not found, or the user does not have access to the folder. | ClientError |
default | An unexpected client error. | ClientError |
POST/workflows/{workflow_id}/startStarts workflow based on request body
Parameters
| Name | In | Required | Type |
|---|---|---|---|
workflow_id | path | yes | string |
Request body
application/json
Responses
| Status | Description | Schema |
|---|---|---|
204 | Starts the workflow. | — |
400 | Returns an error if some of the parameters are missing or not valid. * `workflow_is_not_enabled` when the workflow is not enabled. * `workflow_not_active_on_provided_folder` when the workflow is not enabled for the specified folder id. * `parameters_provided_do_not_match_target_outcome` when the provided parameters do not match the expected parameters. | ClientError |
403 | Returns an error if there are insufficient permissions. * `insufficient_access` when the user does not have access rights to file or folder. * `missing_relay_full_access` when the user does not have access to Relay Full. | ClientError |
404 | Returns an error if the workflow could not be found, or the authenticated user does not have access to the workflow. * `workflow_not_found` when the workflow is not found. * `flow_missing_or_inaccessible` when the flow is not a manual start flow. | ClientError |
default | An unexpected client error. | ClientError |
Zip Downloads3
Zip downloads represent a successful request to create a ZIP archive with files and folders.
POST/zip_downloadsCreate zip download
Request body
application/json — ZipDownloadRequest
Responses
| Status | Description | Schema |
|---|---|---|
202 | If the `zip` archive is ready to be downloaded, the API will return a response that will include a `download_url`, a `status_url`, as well as any conflicts that might have occurred when creating the request. | ZipDownload |
400 | Returns an error if some of the parameters are missing or not valid. In most cases, this error might happen because the JSON request body is not valid JSON, any of the items has an incorrect or missing ID, any of the items is not a file or folder, or the root folder with ID `0` has been added to the list of folders to add to the archive. The following is a list of common error codes for this response. * `bad_request` - the request body is missing, invalid, or both the list of files and folders are empty. Additionally, it this error might be returned when attempting to add the root folder with ID `0` to an archive. * `zip_download_file_count_exceeded_limit` - the requested files and folders would result in an archive with more than 10,000 files. The request will have to be split into multiple requests to reduce the number of files per archive. * `zip_download_pre_compressed_bytes_exceeded_limit` - the requested files and folders would result in an archive with more than the allowed download limit. The request will have to be split into multiple requests to reduce the size of the archive. | ClientError |
401 | Returned when the access token provided in the `Authorization` header is not recognized or not provided. | ClientError |
403 | Returned when an authorization header is provided but the user does not have access to the items. | ClientError |
default | An unexpected client error. | ClientError |
GET/zip_downloads/{zip_download_id}/contentDownload zip archive
Parameters
| Name | In | Required | Type |
|---|---|---|---|
zip_download_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the content of the items requested for this download, formatted as a stream of files and folders in a `zip` archive. | — |
404 | Returns an error if the ID of this download request is not valid. This error can also be returned if this URL has been called before. To re-download this archive, please create a new request for a zip download. | ClientError |
429 | Returns an error if the number of concurrent zip downloads has been reached for either the user or the enterprise. * `user_too_many_concurrent_downloads` - the maximum of 5 parallel downloads of zip archives per user has been met. * `enterprise_too_many_concurrent_downloads` - the maximum of 10 parallel downloads of zip archives per enterprise has been met. | ClientError |
default | An unexpected client error. | ClientError |
GET/zip_downloads/{zip_download_id}/statusGet zip download status
Parameters
| Name | In | Required | Type |
|---|---|---|---|
zip_download_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | Returns the status of the `zip` archive that is being downloaded. | ZipDownloadStatus |
401 | Returned when the access token provided in the `Authorization` header is not recognized or not provided. | ClientError |
403 | Returned when an authorization header is provided but the user does not have access to the items. | ClientError |
404 | Returns an error if the ID of this download request is not valid, or if the status of a download is requested before the download has been started. | ClientError |
default | An unexpected client error. | ClientError |
Try it
Developer reference
Base URL
https://api.box.com/2.0Rate limit
1000 API requests per minute per user for most endpoints, with distinct limits for uploads (240 requests/minute/user) and search (6 requests/second/user, 12/second per enterprise); exceeding a limit returns 429 with a retry-after header.
Key endpoints
- GET/users/me
- GET/folders/{folder_id}
- GET/folders/{folder_id}/items
- GET/files/{file_id}
- GET/search