openapi: 3.0.2
servers:
- description: Box Platform API server
url: https://api.box.com/2.0
info:
contact:
email: devrel@box.com
name: Box, Inc
url: https://box.dev
x-twitter: BoxHQ
description: "[Box Platform](https://box.dev) provides functionality to provide access to content stored within [Box](https://box.com). It provides endpoints for basic manipulation of files and folders, management of users within an enterprise, as well as more complex topics such as legal holds and retention policies."
license:
name: Apache-2.0
url: http://www.apache.org/licenses/LICENSE-2.0
termsOfService: https://cloud.app.box.com/s/rmwxu64h1ipr41u49w3bbuvbsa29wku9
title: Box Platform API
version: 2.0.0
x-apisguru-categories:
- cloud
x-logo:
url: https://twitter.com/BoxHQ/profile_image?size=original
x-origin:
- converter:
url: https://github.com/mermade/oas-kit
version: 7.0.4
format: openapi
url: https://opensource.box.com/box-openapi/openapi.json
version: "3.0"
x-providerName: box.com
externalDocs:
description: Box Developer Documentation
url: https://developer.box.com
security:
- OAuth2Security: []
tags:
- name: Authorization
x-box-priority: true
x-box-tag: authorization
- name: Box Sign
x-box-tag: sign_requests
- name: Classifications
x-box-tag: classifications
- name: Classifications on files
x-box-tag: file_classifications
- name: Classifications on folders
x-box-tag: folder_classifications
- name: Collaborations
x-box-tag: user_collaborations
- name: Collaborations (List)
x-box-tag: list_collaborations
- name: Collections
x-box-tag: collections
- name: Comments
x-box-tag: comments
- name: Device pinners
x-box-tag: device_pinners
- name: Domain restrictions (User exemptions)
x-box-tag: collaboration_allowlist_exempt_targets
- name: Domain restrictions for collaborations
x-box-tag: collaboration_allowlist_entries
- name: Downloads
x-box-tag: downloads
- name: Email aliases
x-box-tag: email_aliases
- name: Events
x-box-tag: events
- name: File requests
x-box-tag: file_requests
- name: File version legal holds
x-box-tag: file_version_legal_holds
- name: File version retentions
x-box-tag: file_version_retentions
- name: File versions
x-box-tag: file_versions
- name: Files
x-box-tag: files
- name: Folder Locks
x-box-tag: folder_locks
- name: Folders
x-box-tag: folders
- name: Group memberships
x-box-tag: memberships
- name: Groups
x-box-tag: groups
- name: Invites
x-box-tag: invites
- name: Legal hold policies
x-box-tag: legal_hold_policies
- name: Legal hold policy assignments
x-box-tag: legal_hold_policy_assignments
- name: Metadata cascade policies
x-box-tag: metadata_cascade_policies
- name: Metadata instances (Files)
x-box-tag: file_metadata
- name: Metadata instances (Folders)
x-box-tag: folder_metadata
- name: Metadata templates
x-box-tag: metadata_templates
- name: Recent items
x-box-tag: recent_items
- name: Retention policies
x-box-tag: retention_policies
- name: Retention policy assignments
x-box-tag: retention_policy_assignments
- name: Search
x-box-tag: search
- name: Session termination
x-box-tag: session_termination
- name: Shared links (Files)
x-box-tag: shared_links_files
- name: Shared links (Folders)
x-box-tag: shared_links_folders
- name: Shared links (Web Links)
x-box-tag: shared_links_web_links
- name: Shield information barriers
x-box-tag: shield_information_barriers
- name: Shield information barrier segments
x-box-tag: shield_information_barrier_segments
- name: Shield information barrier segment members
x-box-tag: shield_information_barrier_segment_members
- name: Shield information barrier reports
x-box-tag: shield_information_barrier_reports
- name: Shield information barrier segment restrictions
x-box-tag: shield_information_barrier_segment_restrictions
- name: Skills
x-box-tag: skills
- name: Standard and Zones Storage Policies
x-box-tag: storage_policies
- name: Standard and Zones Storage Policy Assignments
x-box-tag: storage_policy_assignments
- name: Task assignments
x-box-tag: task_assignments
- name: Tasks
x-box-tag: tasks
- name: Terms of service
x-box-tag: terms_of_services
- name: Terms of service user statuses
x-box-tag: terms_of_service_user_statuses
- name: Termination message
x-box-tag: termination_message
- name: Transfer folders
x-box-tag: transfer
- name: Trashed files
x-box-tag: trashed_files
- name: Trashed folders
x-box-tag: trashed_folders
- name: Trashed items
x-box-tag: trashed_items
- name: Trashed web links
x-box-tag: trashed_web_links
- name: Uploads
x-box-tag: uploads
- name: Uploads (Chunked)
x-box-tag: chunked_uploads
- name: User avatars
x-box-tag: avatars
- name: Users
x-box-tag: users
- name: Watermarks (Files)
x-box-tag: file_watermarks
- name: Watermarks (Folders)
x-box-tag: folder_watermarks
- name: Web links
x-box-tag: web_links
- name: Webhooks
x-box-tag: webhooks
- name: Workflows
x-box-tag: workflows
- name: Zip Downloads
x-box-tag: zip_downloads
paths:
/authorize:
get:
description: |-
Authorize a user by sending them through the [Box](https://box.com)
website and request their permission to act on their behalf.
This is the first step when authenticating a user using
OAuth 2.0. To request a user's authorization to use the Box APIs
on their behalf you will need to send a user to the URL with this
format.
operationId: get_authorize
parameters:
- description: The type of response we'd like to receive.
example: code
in: query
name: response_type
required: true
schema:
enum:
- code
format: token
type: string
- description: |-
The Client ID of the application that is requesting to authenticate
the user. To get the Client ID for your application, log in to your
Box developer console and click the **Edit Application** link for
the application you're working with. In the OAuth 2.0 Parameters section
of the configuration page, find the item labelled `client_id`. The
text of that item is your application's Client ID.
example: ly1nj6n11vionaie65emwzk575hnnmrk
in: query
name: client_id
required: true
schema:
type: string
- description: |-
The URI to which Box redirects the browser after the user has granted
or denied the application permission. This URI match one of the redirect
URIs in the configuration of your application. It must be a
valid HTTPS URI and it needs to be able to handle the redirection to
complete the next step in the OAuth 2.0 flow.
Although this parameter is optional, it must be a part of the
authorization URL if you configured multiple redirect URIs
for the application in the developer console. A missing parameter causes
a `redirect_uri_missing` error after the user grants application access.
example: http://example.com/auth/callback
in: query
name: redirect_uri
required: false
schema:
format: url
type: string
- description: |-
A custom string of your choice. Box will pass the same string to
the redirect URL when authentication is complete. This parameter
can be used to identify a user on redirect, as well as protect
against hijacked sessions and other exploits.
example: my_state
in: query
name: state
required: false
schema:
type: string
- description: |-
A comma-separated list of application scopes you'd like to
authenticate the user for. This defaults to all the scopes configured
for the application in its configuration page.
example: admin_readwrite
in: query
name: scope
required: false
schema:
type: string
responses:
"200":
content:
text/html:
schema:
format: html
type: string
description: Does not return any data, but rather should be used in the browser.
default:
content:
text/html:
schema:
format: html
type: string
description: Does not return any data, but rather should be used in the browser.
security: []
servers:
- description: Server for client-side authentication
url: https://account.box.com/api/oauth2
summary: Authorize user
tags:
- Authorization
x-box-tag: authorization
/collaboration_whitelist_entries:
get:
description: |-
Returns the list domains that have been deemed safe to create collaborations
for within the current enterprise.
operationId: get_collaboration_whitelist_entries
parameters:
- description: |-
Defines the position marker at which to begin returning results. This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
in: query
name: marker
required: false
schema:
type: string
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/CollaborationAllowlistEntries"
description: Returns a collection of domains that are allowed for collaboration.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List allowed collaboration domains
tags:
- Domain restrictions for collaborations
x-box-tag: collaboration_allowlist_entries
post:
description: |-
Creates a new entry in the list of allowed domains to allow
collaboration for.
operationId: post_collaboration_whitelist_entries
requestBody:
content:
application/json:
schema:
properties:
direction:
description: The direction in which to allow collaborations.
enum:
- inbound
- outbound
- both
example: inbound
type: string
domain:
description: The domain to add to the list of allowed domains.
example: example.com
type: string
required:
- domain
- direction
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/CollaborationAllowlistEntry"
description: Returns a new entry on the list of allowed domains.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Add domain to list of allowed collaboration domains
tags:
- Domain restrictions for collaborations
x-box-tag: collaboration_allowlist_entries
"/collaboration_whitelist_entries/{collaboration_whitelist_entry_id}":
delete:
description: |-
Removes a domain from the list of domains that have been deemed safe to create
collaborations for within the current enterprise.
operationId: delete_collaboration_whitelist_entries_id
parameters:
- description: The ID of the entry in the list.
example: "213123"
in: path
name: collaboration_whitelist_entry_id
required: true
schema:
type: string
responses:
"204":
description: |-
A blank response is returned if the entry was
successfully deleted.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Remove domain from list of allowed collaboration domains
tags:
- Domain restrictions for collaborations
x-box-tag: collaboration_allowlist_entries
get:
description: |-
Returns a domain that has been deemed safe to create collaborations
for within the current enterprise.
operationId: get_collaboration_whitelist_entries_id
parameters:
- description: The ID of the entry in the list.
example: "213123"
in: path
name: collaboration_whitelist_entry_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/CollaborationAllowlistEntry"
description: Returns an entry on the list of allowed domains.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get allowed collaboration domain
tags:
- Domain restrictions for collaborations
x-box-tag: collaboration_allowlist_entries
/collaboration_whitelist_exempt_targets:
get:
description: |-
Returns a list of users who have been exempt from the collaboration
domain restrictions.
operationId: get_collaboration_whitelist_exempt_targets
parameters:
- description: |-
Defines the position marker at which to begin returning results. This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
in: query
name: marker
required: false
schema:
type: string
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/CollaborationAllowlistExemptTargets"
description: Returns a collection of user exemptions.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List users exempt from collaboration domain restrictions
tags:
- Domain restrictions (User exemptions)
x-box-tag: collaboration_allowlist_exempt_targets
post:
description: |-
Exempts a user from the restrictions set out by the allowed list of domains
for collaborations.
operationId: post_collaboration_whitelist_exempt_targets
requestBody:
content:
application/json:
schema:
properties:
user:
description: The user to exempt.
properties:
id:
description: The ID of the user to exempt.
example: "23522323"
type: string
required:
- id
type: object
required:
- user
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/CollaborationAllowlistExemptTarget"
description: Returns a new exemption entry.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Create user exemption from collaboration domain restrictions
tags:
- Domain restrictions (User exemptions)
x-box-tag: collaboration_allowlist_exempt_targets
"/collaboration_whitelist_exempt_targets/{collaboration_whitelist_exempt_target_id}":
delete:
description: |-
Removes a user's exemption from the restrictions set out by the allowed list
of domains for collaborations.
operationId: delete_collaboration_whitelist_exempt_targets_id
parameters:
- description: The ID of the exemption to the list.
example: "984923"
in: path
name: collaboration_whitelist_exempt_target_id
required: true
schema:
type: string
responses:
"204":
description: |-
A blank response is returned if the exemption was
successfully deleted.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Remove user from list of users exempt from domain restrictions
tags:
- Domain restrictions (User exemptions)
x-box-tag: collaboration_allowlist_exempt_targets
get:
description: |-
Returns a users who has been exempt from the collaboration
domain restrictions.
operationId: get_collaboration_whitelist_exempt_targets_id
parameters:
- description: The ID of the exemption to the list.
example: "984923"
in: path
name: collaboration_whitelist_exempt_target_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/CollaborationAllowlistExemptTarget"
description: Returns the user's exempted from the list of collaboration domains.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get user exempt from collaboration domain restrictions
tags:
- Domain restrictions (User exemptions)
x-box-tag: collaboration_allowlist_exempt_targets
/collaborations:
get:
description: Retrieves all pending collaboration invites for this user.
operationId: get_collaborations
parameters:
- description: The status of the collaborations to retrieve
example: pending
in: query
name: status
required: true
schema:
enum:
- pending
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
- description: |-
The offset of the item at which to begin the response.
Queries with offset parameter value
exceeding 10000 will be rejected
with a 400 response.
example: 1000
in: query
name: offset
required: false
schema:
default: 0
format: int64
type: integer
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Collaborations"
description: |-
Returns a collection of pending collaboration objects.
If the user has no pending collaborations, the collection
will be empty.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List pending collaborations
tags:
- Collaborations (List)
x-box-tag: list_collaborations
post:
description: |-
Adds a collaboration for a single user or a single group to a file
or folder.
Collaborations can be created using email address, user IDs, or a
group IDs.
If a collaboration is being created with a group, access to
this endpoint is dependent on the group's ability to be invited.
If collaboration is in `pending` status, the following fields
are redacted:
- `login` and `name` are hidden if a collaboration was created
using `user_id`,
- `name` is hidden if a collaboration was created using `login`.
operationId: post_collaborations
parameters:
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
- description: |-
Determines if users should receive email notification
for the action performed.
example: true
in: query
name: notify
required: false
schema:
type: boolean
requestBody:
content:
application/json:
schema:
properties:
accessible_by:
description: The user or group to give access to the item.
properties:
id:
description: |-
The ID of the user or group.
Alternatively, use `login` to specify a user by email
address.
example: "23522323"
type: string
login:
description: |-
The email address of the user to grant access to the item.
Alternatively, use `id` to specify a user by user ID.
example: john@example.com
type: string
type:
description: The type of collaborator to invite.
enum:
- user
- group
example: user
type: string
required:
- type
type: object
can_view_path:
description: |-
Determines if the invited users can see the entire parent path to
the associated folder. The user will not gain privileges in any
parent folder and therefore can not see content the user is not
collaborated on.
Be aware that this meaningfully increases the time required to load the
invitee's **All Files** page. We recommend you limit the number of
collaborations with `can_view_path` enabled to 1,000 per user.
Only owner or co-owners can invite collaborators with a `can_view_path` of
`true`.
`can_view_path` can only be used for folder collaborations.
example: true
type: boolean
expires_at:
description: |-
Set the expiration date for the collaboration. At this date, the
collaboration will be automatically removed from the item.
This feature will only work if the **Automatically remove invited
collaborators: Allow folder owners to extend the expiry date**
setting has been enabled in the **Enterprise Settings**
of the **Admin Console**. When the setting is not enabled,
collaborations can not have an expiry date and a value for this
field will be result in an error.
example: 2019-08-29T23:59:00-07:00
format: date-time
type: string
item:
description: The item to attach the comment to.
properties:
id:
description: The ID of the item that will be granted access to
example: "11446498"
type: string
type:
description: |-
The type of the item that this collaboration will be
granted access to
enum:
- file
- folder
example: file
type: string
required:
- id
- type
type: object
role:
description: The level of access granted.
enum:
- editor
- viewer
- previewer
- uploader
- previewer uploader
- viewer uploader
- co-owner
example: editor
type: string
required:
- item
- accessible_by
- role
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/Collaboration"
description: Returns a new collaboration object.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error when the user does not have the
right permissions to create the collaboration.
* `forbidden_by_policy`: Creating a
collaboration is forbidden due to information
barrier restrictions.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Create collaboration
tags:
- Collaborations
x-box-tag: user_collaborations
"/collaborations/{collaboration_id}":
delete:
description: Deletes a single collaboration.
operationId: delete_collaborations_id
parameters:
- description: The ID of the collaboration
example: "1234"
in: path
name: collaboration_id
required: true
schema:
type: string
responses:
"204":
description: |-
A blank response is returned if the collaboration was
successfully deleted.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Remove collaboration
tags:
- Collaborations
x-box-tag: user_collaborations
get:
description: Retrieves a single collaboration.
operationId: get_collaborations_id
parameters:
- description: The ID of the collaboration
example: "1234"
in: path
name: collaboration_id
required: true
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Collaboration"
description: Returns a collaboration object.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get collaboration
tags:
- Collaborations
x-box-tag: user_collaborations
put:
description: |-
Updates a collaboration.
Can be used to change the owner of an item, or to
accept collaboration invites.
operationId: put_collaborations_id
parameters:
- description: The ID of the collaboration
example: "1234"
in: path
name: collaboration_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
can_view_path:
description: |-
Determines if the invited users can see the entire parent path to
the associated folder. The user will not gain privileges in any
parent folder and therefore can not see content the user is not
collaborated on.
Be aware that this meaningfully increases the time required to load the
invitee's **All Files** page. We recommend you limit the number of
collaborations with `can_view_path` enabled to 1,000 per user.
Only owner or co-owners can invite collaborators with a `can_view_path` of
`true`.
`can_view_path` can only be used for folder collaborations.
example: true
type: boolean
expires_at:
description: |-
Update the expiration date for the collaboration. At this date,
the collaboration will be automatically removed from the item.
This feature will only work if the **Automatically remove invited
collaborators: Allow folder owners to extend the expiry date**
setting has been enabled in the **Enterprise Settings**
of the **Admin Console**. When the setting is not enabled,
collaborations can not have an expiry date and a value for this
field will be result in an error.
Additionally, a collaboration can only be given an
expiration if it was created after the **Automatically remove
invited collaborator** setting was enabled.
example: 2019-08-29T23:59:00-07:00
format: date-time
type: string
role:
description: The level of access granted.
enum:
- editor
- viewer
- previewer
- uploader
- previewer uploader
- viewer uploader
- co-owner
- owner
example: editor
type: string
status:
description: |-
Set the status of a `pending` collaboration invitation,
effectively accepting, or rejecting the invite.
enum:
- pending
- accepted
- rejected
example: accepted
type: string
required:
- role
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Collaboration"
description: Returns an updated collaboration object unless the owner has changed.
"204":
content:
application/json:
schema:
$ref: "#/components/schemas/Collaboration"
description: |-
If the role is changed to `owner`, the collaboration is deleted
and a new collaboration is created. The previous `owner` of
the old collaboration will be a `co-owner` on the new collaboration.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if the authenticated user does not have the right
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Update collaboration
tags:
- Collaborations
x-box-tag: user_collaborations
/collections:
get:
description: |-
Retrieves all collections for a given user.
Currently, only the `favorites` collection
is supported.
operationId: get_collections
parameters:
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
- description: |-
The offset of the item at which to begin the response.
Queries with offset parameter value
exceeding 10000 will be rejected
with a 400 response.
example: 1000
in: query
name: offset
required: false
schema:
default: 0
format: int64
type: integer
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Collections"
description: Returns all collections for the given user
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List all collections
tags:
- Collections
x-box-tag: collections
"/collections/{collection_id}/items":
get:
description: |-
Retrieves the files and/or folders contained within
this collection.
operationId: get_collections_id_items
parameters:
- description: The ID of the collection.
example: "926489"
in: path
name: collection_id
required: true
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
- description: |-
The offset of the item at which to begin the response.
Queries with offset parameter value
exceeding 10000 will be rejected
with a 400 response.
example: 1000
in: query
name: offset
required: false
schema:
default: 0
format: int64
type: integer
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Items"
description: Returns an array of items in the collection.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List collection items
tags:
- Collections
x-box-tag: collections
/comments:
post:
description: |-
Adds a comment by the user to a specific file, or
as a reply to an other comment.
operationId: post_comments
parameters:
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
requestBody:
content:
application/json:
schema:
properties:
item:
description: The item to attach the comment to.
properties:
id:
description: The ID of the item
example: "11446498"
type: string
type:
description: The type of the item that this comment will be placed on.
enum:
- file
- comment
example: file
type: string
required:
- id
- type
type: object
message:
description: |-
The text of the comment.
To mention a user, use the `tagged_message`
parameter instead.
example: Review completed!
type: string
tagged_message:
description: |-
The text of the comment, including `@[user_id:name]`
somewhere in the message to mention another user, which
will send them an email notification, letting them know
they have been mentioned.
The `user_id` is the target user's ID, where the `name`
can be any custom phrase. In the Box UI this name will
link to the user's profile.
If you are not mentioning another user, use `message`
instead.
example: "@[1234:John] Review completed!"
type: string
required:
- message
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/Comment"
description: |-
Returns the newly created comment object.
Not all available fields are returned by default. Use the
[fields](#param-fields) query parameter to explicitly request
any specific fields.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Create comment
tags:
- Comments
x-box-tag: comments
"/comments/{comment_id}":
delete:
description: Permanently deletes a comment.
operationId: delete_comments_id
parameters:
- description: The ID of the comment.
example: "12345"
in: path
name: comment_id
required: true
schema:
type: string
responses:
"204":
description: Returns an empty response when the comment has been deleted.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Remove comment
tags:
- Comments
x-box-tag: comments
get:
description: |-
Retrieves the message and metadata for a specific comment, as well
as information on the user who created the comment.
operationId: get_comments_id
parameters:
- description: The ID of the comment.
example: "12345"
in: path
name: comment_id
required: true
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Comment--Full"
description: Returns a full comment object.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get comment
tags:
- Comments
x-box-tag: comments
put:
description: Update the message of a comment.
operationId: put_comments_id
parameters:
- description: The ID of the comment.
example: "12345"
in: path
name: comment_id
required: true
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
requestBody:
content:
application/json:
schema:
properties:
message:
description: The text of the comment to update
example: Review completed!
type: string
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Comment--Full"
description: Returns the updated comment object.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Update comment
tags:
- Comments
x-box-tag: comments
"/device_pinners/{device_pinner_id}":
delete:
description: Deletes an individual device pin.
operationId: delete_device_pinners_id
parameters:
- description: The ID of the device pin
example: "2324234"
in: path
name: device_pinner_id
required: true
schema:
type: string
responses:
"204":
description: Returns an empty response when the pin has been deleted.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Remove device pin
tags:
- Device pinners
x-box-tag: device_pinners
get:
description: Retrieves information about an individual device pin.
operationId: get_device_pinners_id
parameters:
- description: The ID of the device pin
example: "2324234"
in: path
name: device_pinner_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/DevicePinner"
description: Returns information about a single device pin.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get device pin
tags:
- Device pinners
x-box-tag: device_pinners
"/enterprises/{enterprise_id}/device_pinners":
get:
description: |-
Retrieves all the device pins within an enterprise.
The user must have admin privileges, and the application
needs the "manage enterprise" scope to make this call.
operationId: get_enterprises_id_device_pinners
parameters:
- description: The ID of the enterprise
example: "3442311"
in: path
name: enterprise_id
required: true
schema:
type: string
- description: |-
Defines the position marker at which to begin returning results. This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
in: query
name: marker
required: false
schema:
type: string
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
- description: |-
The direction to sort results in. This can be either in alphabetical ascending
(`ASC`) or descending (`DESC`) order.
example: ASC
in: query
name: direction
required: false
schema:
enum:
- ASC
- DESC
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/DevicePinners"
description: Returns a list of device pins for a given enterprise.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List enterprise device pins
tags:
- Device pinners
x-box-tag: device_pinners
/events:
get:
description: |-
Returns up to a year of past events for a given user
or for the entire enterprise.
By default this returns events for the authenticated user. To retrieve events
for the entire enterprise, set the `stream_type` to `admin_logs_streaming`
for live monitoring of new events, or `admin_logs` for querying across
historical events. The user making the API call will
need to have admin privileges, and the application will need to have the
scope `manage enterprise properties` checked.
operationId: get_events
parameters:
- description: |-
Defines the type of events that are returned
* `all` returns everything for a user and is the default
* `changes` returns events that may cause file tree changes
such as file updates or collaborations.
* `sync` is similar to `changes` but only applies to synced folders
* `admin_logs` returns all events for an entire enterprise and
requires the user making the API call to have admin permissions. This
stream type is for programmatically pulling from a 1 year history of
events across all users within the enterprise and within a
`created_after` and `created_before` time frame. The complete history
of events will be returned in chronological order based on the event
time, but latency will be much higher than `admin_logs_streaming`.
* `admin_logs_streaming` returns all events for an entire enterprise and
requires the user making the API call to have admin permissions. This
stream type is for polling for recent events across all users within
the enterprise. Latency will be much lower than `admin_logs`, but
events will not be returned in chronological order and may
contain duplicates.
example: all
in: query
name: stream_type
schema:
default: all
enum:
- all
- changes
- sync
- admin_logs
- admin_logs_streaming
type: string
- description: |-
The location in the event stream to start receiving events from.
* `now` will return an empty list events and
the latest stream position for initialization.
* `0` or `null` will return all events.
example: "1348790499819"
in: query
name: stream_position
schema:
type: string
- description: |-
Limits the number of events returned
Note: Sometimes, the events less than the limit requested can be returned
even when there may be more events remaining. This is primarily done in
the case where a number of events have already been retrieved and these
retrieved events are returned rather than delaying for an unknown amount
of time to see if there are any more results.
example: 50
in: query
name: limit
schema:
default: 100
format: int64
maximum: 500
type: integer
- description: |-
A comma-separated list of events to filter by. This can only be used when
requesting the events with a `stream_type` of `admin_logs` or
`adming_logs_streaming`. For any other `stream_type` this value will be
ignored.
example:
- ACCESS_GRANTED
explode: false
in: query
name: event_type
schema:
items:
description: An event type that can be filtered by
enum:
- ACCESS_GRANTED
- ACCESS_REVOKED
- ADD_DEVICE_ASSOCIATION
- ADD_LOGIN_ACTIVITY_DEVICE
- ADMIN_LOGIN
- APPLICATION_CREATED
- APPLICATION_PUBLIC_KEY_ADDED
- APPLICATION_PUBLIC_KEY_DELETED
- CHANGE_ADMIN_ROLE
- CHANGE_FOLDER_PERMISSION
- COLLABORATION_ACCEPT
- COLLABORATION_EXPIRATION
- COLLABORATION_INVITE
- COLLABORATION_REMOVE
- COLLABORATION_ROLE_CHANGE
- COMMENT_CREATE
- COMMENT_DELETE
- CONTENT_WORKFLOW_ABNORMAL_DOWNLOAD_ACTIVITY
- CONTENT_WORKFLOW_AUTOMATION_ADD
- CONTENT_WORKFLOW_AUTOMATION_DELETE
- CONTENT_WORKFLOW_POLICY_ADD
- CONTENT_WORKFLOW_SHARING_POLICY_VIOLATION
- CONTENT_WORKFLOW_UPLOAD_POLICY_VIOLATION
- COPY
- DATA_RETENTION_CREATE_RETENTION
- DATA_RETENTION_REMOVE_RETENTION
- DELETE
- DELETE_USER
- DEVICE_TRUST_CHECK_FAILED
- DOWNLOAD
- EDIT
- EDIT_USER
- EMAIL_ALIAS_CONFIRM
- EMAIL_ALIAS_REMOVE
- ENTERPRISE_APP_AUTHORIZATION_UPDATE
- EXTERNAL_COLLAB_SECURITY_SETTINGS
- FAILED_LOGIN
- FILE_MARKED_MALICIOUS
- FILE_WATERMARKED_DOWNLOAD
- GROUP_ADD_ITEM
- GROUP_ADD_USER
- GROUP_CREATION
- GROUP_DELETION
- GROUP_EDITED
- GROUP_REMOVE_ITEM
- GROUP_REMOVE_USER
- ITEM_MODIFY
- ITEM_OPEN
- ITEM_SHARED_UPDATE
- ITEM_SYNC
- ITEM_UNSYNC
- LEGAL_HOLD_ASSIGNMENT_CREATE
- LEGAL_HOLD_ASSIGNMENT_DELETE
- LEGAL_HOLD_POLICY_CREATE
- LEGAL_HOLD_POLICY_DELETE
- LEGAL_HOLD_POLICY_UPDATE
- LOCK
- LOGIN
- METADATA_INSTANCE_CREATE
- METADATA_INSTANCE_DELETE
- METADATA_INSTANCE_UPDATE
- METADATA_TEMPLATE_CREATE
- METADATA_TEMPLATE_DELETE
- METADATA_TEMPLATE_UPDATE
- MOVE
- NEW_USER
- OAUTH2_ACCESS_TOKEN_REVOKE
- PREVIEW
- REMOVE_DEVICE_ASSOCIATION
- REMOVE_LOGIN_ACTIVITY_DEVICE
- RENAME
- RETENTION_POLICY_ASSIGNMENT_ADD
- SHARE
- SHARE_EXPIRATION
- SHIELD_ALERT
- SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED
- SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED_MISSING_JUSTIFICATION
- SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED
- SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED_MISSING_JUSTIFICATION
- SHIELD_JUSTIFICATION_APPROVAL
- SIGN_DOCUMENT_ASSIGNED
- SIGN_DOCUMENT_CANCELLED
- SIGN_DOCUMENT_COMPLETED
- SIGN_DOCUMENT_CONVERTED
- SIGN_DOCUMENT_CREATED
- SIGN_DOCUMENT_DECLINED
- SIGN_DOCUMENT_EXPIRED
- SIGN_DOCUMENT_SIGNED
- SIGN_DOCUMENT_VIEWED_BY_SIGNED
- SIGNER_DOWNLOADED
- SIGNER_FORWARDED
- STORAGE_EXPIRATION
- TASK_ASSIGNMENT_CREATE
- TASK_ASSIGNMENT_DELETE
- TASK_ASSIGNMENT_UPDATE
- TASK_CREATE
- TASK_UPDATE
- TERMS_OF_SERVICE_ACCEPT
- TERMS_OF_SERVICE_REJECT
- UNDELETE
- UNLOCK
- UNSHARE
- UPDATE_COLLABORATION_EXPIRATION
- UPDATE_SHARE_EXPIRATION
- UPLOAD
- USER_AUTHENTICATE_OAUTH2_ACCESS_TOKEN_CREATE
- WATERMARK_LABEL_CREATE
- WATERMARK_LABEL_DELETE
type: string
type: array
- description: |-
The lower bound date and time to return events for. This can only be used
when requesting the events with a `stream_type` of `admin_logs`. For any
other `stream_type` this value will be ignored.
example: 2012-12-12T10:53:43-08:00
in: query
name: created_after
schema:
format: date-time
type: string
- description: |-
The upper bound date and time to return events for. This can only be used
when requesting the events with a `stream_type` of `admin_logs`. For any
other `stream_type` this value will be ignored.
example: 2013-12-12T10:53:43-08:00
in: query
name: created_before
required: false
schema:
format: date-time
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Events"
description: |-
Returns a list of event objects.
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List user and enterprise events
tags:
- Events
x-box-tag: events
options:
description: |-
Returns a list of real-time servers that can be used for long-polling updates
to the [event stream](#get-events).
Long polling is the concept where a HTTP request is kept open until the
server sends a response, then repeating the process over and over to receive
updated responses.
Long polling the event stream can only be used for user events, not for
enterprise events.
To use long polling, first use this endpoint to retrieve a list of long poll
URLs. Next, make a long poll request to any of the provided URLs.
When an event occurs in monitored account a response with the value
`new_change` will be sent. The response contains no other details as
it only serves as a prompt to take further action such as sending a
request to the [events endpoint](#get-events) with the last known
`stream_position`.
After the server sends this response it closes the connection. You must now
repeat the long poll process to begin listening for events again.
If no events occur for a while and the connection times out you will
receive a response with the value `reconnect`. When you receive this response
you’ll make another call to this endpoint to restart the process.
If you receive no events in `retry_timeout` seconds then you will need to
make another request to the real-time server (one of the URLs in the response
for this endpoint). This might be necessary due to network errors.
Finally, if you receive a `max_retries` error when making a request to the
real-time server, you should start over by making a call to this endpoint
first.
operationId: options_events
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/RealtimeServers"
description: |-
Returns a paginated array of servers that can be used
instead of the regular endpoints for long-polling events.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get events long poll endpoint
tags:
- Events
x-box-tag: events
"/file_requests/{file_request_id}":
delete:
description: Deletes a file request permanently.
operationId: delete_file_requests_id
parameters:
- description: |-
The unique identifier that represent a file request.
The ID for any file request can be determined
by visiting a file request builder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/filerequest/123`
the `file_request_id` is `123`.
example: "123"
in: path
name: file_request_id
required: true
schema:
type: string
responses:
"204":
description: |-
Returns an empty response when the file request has been successfully
deleted.
"401":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when the access token provided in the `Authorization` header
is not recognized or not provided.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned if the file request is not found or has already been deleted,
or the user does not have access to the associated folder.
"405":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned if the `file_request_id` is not in a recognized format.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Delete file request
tags:
- File requests
x-box-sanitized: true
x-box-tag: file_requests
get:
description: Retrieves the information about a file request.
operationId: get_file_requests_id
parameters:
- description: |-
The unique identifier that represent a file request.
The ID for any file request can be determined
by visiting a file request builder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/filerequest/123`
the `file_request_id` is `123`.
example: "123"
in: path
name: file_request_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/FileRequest"
description: Returns a file request object.
"401":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when the access token provided in the `Authorization` header
is not recognized or not provided.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned if the file request is not found, or the user does not
have access to the associated folder.
"405":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned if the `file_request_id` is not in a recognized format.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get file request
tags:
- File requests
x-box-enable-explorer: true
x-box-tag: file_requests
put:
description: |-
Updates a file request. This can be used to activate or
deactivate a file request.
operationId: put_file_requests_id
parameters:
- description: |-
The unique identifier that represent a file request.
The ID for any file request can be determined
by visiting a file request builder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/filerequest/123`
the `file_request_id` is `123`.
example: "123"
in: path
name: file_request_id
required: true
schema:
type: string
- description: |-
Ensures this item hasn't recently changed before
making changes.
Pass in the item's last observed `etag` value
into this header and the endpoint will fail
with a `412 Precondition Failed` if it
has changed since.
example: "1"
in: header
name: if-match
required: false
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/FileRequestUpdateRequest"
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/FileRequest"
description: Returns the updated file request object.
"401":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when the access token provided in the `Authorization` header
is not recognized or not provided.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned if the file request is not found, or the user does not
have access to the associated folder.
"405":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned if the `file_request_id` is not in a recognized format.
"412":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Update file request
tags:
- File requests
x-box-enable-explorer: true
x-box-sanitized: true
x-box-tag: file_requests
"/file_requests/{file_request_id}/copy":
post:
description: |-
Copies an existing file request that is already present on one folder,
and applies it to another folder.
operationId: post_file_requests_id_copy
parameters:
- description: |-
The unique identifier that represent a file request.
The ID for any file request can be determined
by visiting a file request builder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/filerequest/123`
the `file_request_id` is `123`.
example: "123"
in: path
name: file_request_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/FileRequestCopyRequest"
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/FileRequest"
description: Returns updated file request object.
"401":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when the access token provided in the `Authorization` header
is not recognized or not provided.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned if the file request is not found, or the user does not
have access to the associated folder.
"405":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned if the `file_request_id` is not in a recognized format.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Copy file request
tags:
- File requests
x-box-enable-explorer: true
x-box-sanitized: true
x-box-tag: file_requests
/file_version_legal_holds:
get:
description: |-
Get a list of file versions on legal hold for a legal hold
assignment.
Due to ongoing re-architecture efforts this API might not return all file
versions for this policy ID.
Instead, this API will only return file versions held in the legacy
architecture. Two new endpoints will available to request any file versions
held in the new architecture.
For file versions held in the new architecture, the `GET
/legal_hold_policy_assignments/:id/file_versions_on_hold` API can be used to
return all past file versions available for this policy assignment, and the
`GET /legal_hold_policy_assignments/:id/files_on_hold` API can be used to
return any current (latest) versions of a file under legal hold.
The `GET /legal_hold_policy_assignments?policy_id={id}` API can be used to
find a list of policy assignments for a given policy ID.
Once the re-architecture is completed this API will be deprecated.
operationId: get_file_version_legal_holds
parameters:
- description: |-
The ID of the legal hold policy to get the file version legal
holds for.
example: "133870"
in: query
name: policy_id
required: true
schema:
type: string
- description: |-
Defines the position marker at which to begin returning results. This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
in: query
name: marker
required: false
schema:
type: string
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/FileVersionLegalHolds"
description: |-
Returns the list of file version legal holds for a specific legal
hold policy.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List file version legal holds
tags:
- File version legal holds
x-box-tag: file_version_legal_holds
"/file_version_legal_holds/{file_version_legal_hold_id}":
get:
description: |-
Retrieves information about the legal hold policies
assigned to a file version.
operationId: get_file_version_legal_holds_id
parameters:
- description: The ID of the file version legal hold
example: "2348213"
in: path
name: file_version_legal_hold_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/FileVersionLegalHold"
description: Returns the legal hold policy assignments for the file version.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get file version legal hold
tags:
- File version legal holds
x-box-tag: file_version_legal_holds
/file_version_retentions:
get:
description: Retrieves all file version retentions for the given enterprise.
operationId: get_file_version_retentions
parameters:
- description: Filters results by files with this ID.
example: "43123123"
in: query
name: file_id
required: false
schema:
type: string
- description: Filters results by file versions with this ID.
example: "1"
in: query
name: file_version_id
required: false
schema:
type: string
- description: Filters results by the retention policy with this ID.
example: "982312"
in: query
name: policy_id
required: false
schema:
type: string
- description: |-
Filters results by the retention policy with this disposition
action.
example: permanently_delete
in: query
name: disposition_action
required: false
schema:
enum:
- permanently_delete
- remove_retention
type: string
- description: |-
Filters results by files that will have their disposition
come into effect before this date.
example: 2012-12-12T10:53:43-08:00
in: query
name: disposition_before
required: false
schema:
type: string
- description: |-
Filters results by files that will have their disposition
come into effect after this date.
example: 2012-12-19T10:34:23-08:00
in: query
name: disposition_after
required: false
schema:
type: string
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
- description: |-
Defines the position marker at which to begin returning results. This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
in: query
name: marker
required: false
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/FileVersionRetentions"
description: Returns a list of all file version retentions for the enterprise.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List file version retentions
tags:
- File version retentions
x-box-tag: file_version_retentions
"/file_version_retentions/{file_version_retention_id}":
get:
description: Returns information about a file version retention.
operationId: get_file_version_retentions_id
parameters:
- description: The ID of the file version retention
example: "3424234"
in: path
name: file_version_retention_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/FileVersionRetention"
description: Returns a file version retention object.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get retention on file
tags:
- File version retentions
x-box-tag: file_version_retentions
/files/content:
options:
description: |-
Performs a check to verify that a file will be accepted by Box
before you upload the entire file.
operationId: options_files_content
requestBody:
content:
application/json:
schema:
properties:
name:
description: The name for the file
example: File.mp4
type: string
parent:
allOf:
- description: The parent for this item
properties:
id:
description: The ID of parent item
example: "123"
type: string
type: object
- description: The parent folder to upload the file to
size:
description: The size of the file in bytes
example: 1024
format: int32
type: integer
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/UploadUrl"
description: |-
If the check passed, the response will include a session URL that
can be used to upload the file to.
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ConflictError"
description: |-
If the check did not pass, the response will include some details on
why it did not pass.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Preflight check before upload
tags:
- Files
x-box-tag: uploads
post:
description: |-
Uploads a small file to Box. For file sizes over 50MB we recommend
using the Chunk Upload APIs.
# Request body order
The `attributes` part of the body must come **before** the
`file` part. Requests that do not follow this format when
uploading the file will receive a HTTP `400` error with a
`metadata_after_file_contents` error code.
operationId: post_files_content
parameters:
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
- description: |-
An optional header containing the SHA1 hash of the file to
ensure that the file was not corrupted in transit.
example: 134b65991ed521fcfe4724b7d814ab8ded5185dc
in: header
name: content-md5
required: false
schema:
type: string
requestBody:
content:
multipart/form-data:
schema:
properties:
attributes:
description: |-
The additional attributes of the file being uploaded. Mainly the
name and the parent folder. These attributes are part of the multi
part request body and are in JSON format.
The `attributes` part of the body must come **before** the
`file` part. Requests that do not follow this format when
uploading the file will receive a HTTP `400` error with a
`metadata_after_file_contents` error code.
properties:
content_created_at:
description: |-
Defines the time the file was originally created at.
If not set, the upload time will be used.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
content_modified_at:
description: |-
Defines the time the file was last modified at.
If not set, the upload time will be used.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
name:
description: The name of the file
example: Photo.png
type: string
parent:
description: The parent folder to upload the file to
properties:
id:
description: |-
The id of the parent folder. Use
`0` for the user's root folder.
example: "124132"
type: string
required:
- id
type: object
required:
- name
- parent
type: object
file:
description: |-
The content of the file to upload to Box.
The `attributes` part of the body must come **before** the
`file` part. Requests that do not follow this format when
uploading the file will receive a HTTP `400` error with a
`metadata_after_file_contents` error code.
format: binary
type: string
required:
- attributes
- file
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/Files"
description: Returns the new file object in a list.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if the file already exists,
or the account has run out of disk space.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
servers:
- description: Server for file uploads
url: https://upload.box.com/api/2.0
summary: Upload file
tags:
- Uploads
x-box-tag: uploads
/files/upload_sessions:
post:
description: Creates an upload session for a new file.
operationId: post_files_upload_sessions
requestBody:
content:
application/json:
schema:
properties:
file_name:
description: The name of new file
example: Project.mov
type: string
file_size:
description: The total number of bytes of the file to be uploaded
example: 104857600
format: int64
type: integer
folder_id:
description: The ID of the folder to upload the new file to.
example: "0"
type: string
required:
- folder_id
- file_size
- file_name
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/UploadSession"
description: Returns a new upload session.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if the operation is not allowed for some reason.
* `storage_limit_exceeded`: Account storage limit reached
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if the file already exists,
or the account has run out of disk space.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
servers:
- description: Server for file uploads
url: https://upload.box.com/api/2.0
summary: Create upload session
tags:
- Uploads (Chunked)
x-box-tag: chunked_uploads
"/files/upload_sessions/{upload_session_id}":
delete:
description: |-
Abort an upload session and discard all data uploaded.
This cannot be reversed.
operationId: delete_files_upload_sessions_id
parameters:
- description: The ID of the upload session.
example: D5E3F7A
in: path
name: upload_session_id
required: true
schema:
type: string
responses:
"204":
description: |-
A blank response is returned if the session was
successfully aborted.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
servers:
- description: Server for file uploads
url: https://upload.box.com/api/2.0
summary: Remove upload session
tags:
- Uploads (Chunked)
x-box-tag: chunked_uploads
get:
description: Return information about an upload session.
operationId: get_files_upload_sessions_id
parameters:
- description: The ID of the upload session.
example: D5E3F7A
in: path
name: upload_session_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/UploadSession"
description: Returns an upload session object.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
servers:
- description: Server for file uploads
url: https://upload.box.com/api/2.0
summary: Get upload session
tags:
- Uploads (Chunked)
x-box-tag: chunked_uploads
put:
description: Updates a chunk of an upload session for a file.
operationId: put_files_upload_sessions_id
parameters:
- description: The ID of the upload session.
example: D5E3F7A
in: path
name: upload_session_id
required: true
schema:
type: string
- description: |-
The [RFC3230][1] message digest of the chunk uploaded.
Only SHA1 is supported. The SHA1 digest must be base64
encoded. The format of this header is as
`sha=BASE64_ENCODED_DIGEST`.
To get the value for the `SHA` digest, use the
openSSL command to encode the file part:
`openssl sha1 -binary | base64`
[1]: https://tools.ietf.org/html/rfc3230
example: sha=fpRyg5eVQletdZqEKaFlqwBXJzM=
in: header
name: digest
required: true
schema:
type: string
- description: |-
The byte range of the chunk.
Must not overlap with the range of a part already
uploaded this session. Each part’s size must be
exactly equal in size to the part size specified
in the upload session that you created.
One exception is the last part of the file, as this can be smaller.
When providing the value for `content-range`, remember that:
* The lower bound of each part's byte range
must be a multiple of the part size.
* The higher bound must be a multiple of the part size - 1.
example: bytes 8388608-16777215/445856194
in: header
name: content-range
required: true
schema:
type: string
requestBody:
content:
application/octet-stream:
schema:
description: The binary content of the file
format: binary
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/UploadedPart"
description: Chunk has been uploaded successfully.
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if the chunk conflicts with another
chunk previously uploaded.
"412":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if a precondition was not met.
"416":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if the content range does not match a specified range
for the session.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
servers:
- description: Server for file uploads
url: https://upload.box.com/api/2.0
summary: Upload part of file
tags:
- Uploads (Chunked)
x-box-tag: chunked_uploads
"/files/upload_sessions/{upload_session_id}/commit":
post:
description: |-
Close an upload session and create a file from the
uploaded chunks.
operationId: post_files_upload_sessions_id_commit
parameters:
- description: The ID of the upload session.
example: D5E3F7A
in: path
name: upload_session_id
required: true
schema:
type: string
- description: |-
The [RFC3230][1] message digest of the whole file.
Only SHA1 is supported. The SHA1 digest must be Base64
encoded. The format of this header is as
`sha=BASE64_ENCODED_DIGEST`.
[1]: https://tools.ietf.org/html/rfc3230
example: sha=fpRyg5eVQletdZqEKaFlqwBXJzM=
in: header
name: digest
required: true
schema:
type: string
- description: |-
Ensures this item hasn't recently changed before
making changes.
Pass in the item's last observed `etag` value
into this header and the endpoint will fail
with a `412 Precondition Failed` if it
has changed since.
example: "1"
in: header
name: if-match
required: false
schema:
type: string
- description: |-
Ensures an item is only returned if it has changed.
Pass in the item's last observed `etag` value
into this header and the endpoint will fail
with a `304 Not Modified` if the item has not
changed since.
example: "1"
in: header
name: if-none-match
required: false
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
parts:
description: The list details for the uploaded parts
items:
$ref: "#/components/schemas/UploadPart"
type: array
required:
- parts
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/Files"
description: Returns the file object in a list.
"202":
description: |-
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.
headers:
Retry-After:
description: |-
Indicates the number of seconds the client should wait before
attempting their commit request again.
schema:
type: integer
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if there is already a file with the same name
in the target folder.
"412":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if the `If-Match` or `If-None-Match` conditions fail.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
servers:
- description: Server for file uploads
url: https://upload.box.com/api/2.0
summary: Commit upload session
tags:
- Uploads (Chunked)
x-box-tag: chunked_uploads
"/files/upload_sessions/{upload_session_id}/parts":
get:
description: |-
Return a list of the chunks uploaded to the upload
session so far.
operationId: get_files_upload_sessions_id_parts
parameters:
- description: The ID of the upload session.
example: D5E3F7A
in: path
name: upload_session_id
required: true
schema:
type: string
- description: |-
The offset of the item at which to begin the response.
Queries with offset parameter value
exceeding 10000 will be rejected
with a 400 response.
example: 1000
in: query
name: offset
required: false
schema:
default: 0
format: int64
type: integer
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/UploadParts"
description: Returns a list of parts that have been uploaded.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
servers:
- description: Server for file uploads
url: https://upload.box.com/api/2.0
summary: List parts
tags:
- Uploads (Chunked)
x-box-tag: chunked_uploads
"/files/{file_id}":
delete:
description: |-
Deletes a file, either permanently or by moving it to
the trash.
The the enterprise settings determine whether the item will
be permanently deleted from Box or moved to the trash.
operationId: delete_files_id
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
- description: |-
Ensures this item hasn't recently changed before
making changes.
Pass in the item's last observed `etag` value
into this header and the endpoint will fail
with a `412 Precondition Failed` if it
has changed since.
example: "1"
in: header
name: if-match
required: false
schema:
type: string
responses:
"204":
description: |-
Returns an empty response when the file has been successfully
deleted.
"401":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when the access token provided in the `Authorization` header
is not recognized or not provided.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned if the file is not found or has already been deleted, or the user
does not have access to the file.
"405":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned if the `file_id` is not in a recognized format.
"412":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Delete file
tags:
- Files
x-box-sanitized: true
x-box-tag: files
get:
description: Retrieves the details about a file.
operationId: get_files_id
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
Additionally this field can be used to query any metadata
applied to the file by specifying the `metadata` field as well
as the scope and key of the template to retrieve, for example
`?field=metadata.enterprise_12345.contractTemplate`.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
- description: |-
Ensures an item is only returned if it has changed.
Pass in the item's last observed `etag` value
into this header and the endpoint will fail
with a `304 Not Modified` if the item has not
changed since.
example: "1"
in: header
name: if-none-match
required: false
schema:
type: string
- description: |-
The URL, and optional password, for the shared link of this item.
This header can be used to access items that have not been
explicitly shared with a user.
Use the format `shared_link=[link]` or if a password is required then
use `shared_link=[link]&shared_link_password=[password]`.
This header can be used on the file or folder shared, as well as on any files
or folders nested within the item.
example: shared_link=[link]&shared_link_password=[password]
in: header
name: boxapi
required: false
schema:
type: string
- description: |-
A header required to request specific `representations`
of a file. Use this in combination with the `fields` query
parameter to request a specific file representation.
The general format for these representations is
`X-Rep-Hints: [...]` where `[...]` is one or many
hints in the format `[fileType?query]`.
For example, to request a `png` representation in `32x32`
as well as `64x64` pixel dimensions provide the following
hints.
`x-rep-hints: [jpg?dimensions=32x32][jpg?dimensions=64x64]`
Additionally, a `text` representation is available for all
document file types in Box using the `[extracted_text]`
representation.
`x-rep-hints: [extracted_text]`
example: "[pdf]"
in: header
name: x-rep-hints
required: false
schema:
nullable: true
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/File--Full"
description: |-
Returns a file object.
Not all available fields are returned by default. Use the
[fields](#param-fields) query parameter to explicitly request
any specific fields.
"304":
description: |-
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":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when the access token provided in the `Authorization` header
is not recognized or not provided.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned if the file is not found, or the user does not
have access to the file.
"405":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned if the `file_id` is not in a recognized format.
"415":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get file information
tags:
- Files
x-box-enable-explorer: true
x-box-tag: files
post:
description: |-
Restores a file that has been moved to the trash.
An optional new parent ID can be provided to restore the file to in case the
original folder has been deleted.
operationId: post_files_id
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
requestBody:
content:
application/json:
schema:
properties:
name:
description: An optional new name for the file.
example: Restored.docx
type: string
parent:
allOf:
- description: The parent for this item
properties:
id:
description: The ID of parent item
example: "123"
type: string
type: object
- description: |-
Specifies an optional ID of a folder to restore the file to
when the original folder no longer exists.
Please be aware that this ID will only be used if the original
folder no longer exists. Use this ID to provide a fallback
location to restore the file to if the original location
has been deleted.
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/TrashFileRestored"
description: Returns a file object when the file has been restored.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if the file is not in the trash.
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if there is an file with the same name
in the folder the file is being restored to.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Restore file
tags:
- Trashed files
x-box-tag: trashed_files
put:
description: |-
Updates a file. This can be used to rename or move a file,
create a shared link, or lock a file.
operationId: put_files_id
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
- description: |-
Ensures this item hasn't recently changed before
making changes.
Pass in the item's last observed `etag` value
into this header and the endpoint will fail
with a `412 Precondition Failed` if it
has changed since.
example: "1"
in: header
name: if-match
required: false
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
description:
description: |-
The description for a file. This can be seen in the right-hand sidebar panel
when viewing a file in the Box web app. Additionally, this index is used in
the search index of the file, allowing users to find the file by the content
in the description.
example: The latest reports. Automatically updated
maxLength: 256
type: string
disposition_at:
description: |-
The retention expiration timestamp for the given file. This
date cannot be shortened once set on a file.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
lock:
description: |-
Defines a lock on an item. This prevents the item from being
moved, renamed, or otherwise changed by anyone other than the user
who created the lock.
Set this to `null` to remove the lock.
properties:
access:
description: The type of this object.
enum:
- lock
example: lock
type: string
expires_at:
description: Defines the time at which the lock expires.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
is_download_prevented:
description: Defines if the file can be downloaded while it is locked.
example: true
type: boolean
required:
- type
type: object
name:
description: |-
An optional different name for the file. This can be used to
rename the file.
example: NewFile.txt
type: string
parent:
allOf:
- description: The parent for this item
properties:
id:
description: The ID of parent item
example: "123"
type: string
type: object
- description: |-
An optional new parent folder for the file. This can be used
to move the file to a new folder.
permissions:
description: Defines who can download a file.
properties:
can_download:
description: |-
Defines who is allowed to download this file. The possible
values are either `open` for everyone or `company` for
the other members of the user's enterprise.
This setting overrides the download permissions that are
normally part of the `role` of a collaboration. When set to
`company`, this essentially removes the download option for
external users with `viewer` or `editor` a roles.
enum:
- open
- company
example: open
type: string
type: object
shared_link:
allOf:
- description: |-
Defines a shared link for an item. Set this to `null` to remove
the shared link.
properties:
access:
description: |-
The level of access for the shared link. This can be
restricted to anyone with the link (`open`), only people
within the company (`company`) and only those who
have been invited to the folder (`collaborators`).
If not set, this field defaults to the access level specified
by the enterprise admin. To create a shared link with this
default setting pass the `shared_link` object with
no `access` field, for example `{ "shared_link": {} }`.
The `company` access level is only available to paid
accounts.
enum:
- open
- company
- collaborators
example: open
type: string
password:
description: |-
The password required to access the shared link. Set the
password to `null` to remove it.
A password can only be set when `access` is set to `open`.
example: do-not-use-this-password
type: string
permissions:
properties:
can_download:
description: |-
If the shared link allows for downloading of files.
This can only be set when `access` is set to
`open` or `company`.
example: true
type: boolean
type: object
unshared_at:
description: |-
The timestamp at which this shared link will
expire. This field can only be set by
users with paid accounts.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
vanity_name:
description: |-
Defines a custom vanity name to use in the shared link URL,
for example `https://app.box.com/v/my-shared-link`.
Custom URLs should not be used when sharing sensitive content
as vanity URLs are a lot easier to guess than regular shared links.
example: my-shared-link
type: string
type: object
- description: |-
Defines a shared link for a file. Set this to `null` to remove
the shared link.
tags:
description: |-
The tags for this item. These tags are shown in
the Box web app and mobile apps next to an item.
To add or remove a tag, retrieve the item's current tags,
modify them, and then update this field.
There is a limit of 100 tags per item, and 10,000
unique tags per enterprise.
example:
- approved
items:
type: string
maxItems: 100
minItems: 1
type: array
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/File--Full"
description: |-
Returns a file object.
Not all available fields are returned by default. Use the
[fields](#param-fields) query parameter to explicitly request
any specific fields.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned when the new retention time > maximum retention length.
"401":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when the access token provided in the `Authorization` header
is not recognized or not provided.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned if the file is not found, or the user does not
have access to the file.
"405":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned if the `file_id` is not in a recognized format.
"412":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Update file
tags:
- Files
x-box-enable-explorer: true
x-box-sanitized: true
x-box-tag: files
"/files/{file_id}#add_shared_link":
put:
description: Adds a shared link to a file.
operationId: put_files_id#add_shared_link
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
- description: |-
Explicitly request the `shared_link` fields
to be returned for this item.
example: shared_link
in: query
name: fields
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
shared_link:
description: |-
The settings for the shared link to create on the file.
Use an empty object (`{}`) to use the default settings for shared
links.
properties:
access:
description: |-
The level of access for the shared link. This can be
restricted to anyone with the link (`open`), only people
within the company (`company`) and only those who
have been invited to the file (`collaborators`).
If not set, this field defaults to the access level specified
by the enterprise admin. To create a shared link with this
default setting pass the `shared_link` object with
no `access` field, for example `{ "shared_link": {} }`.
The `company` access level is only available to paid
accounts.
enum:
- open
- company
- collaborators
example: open
type: string
password:
description: |-
The password required to access the shared link. Set the
password to `null` to remove it.
A password can only be set when `access` is set to `open`.
example: do-not-use-this-password
type: string
permissions:
properties:
can_download:
description: |-
If the shared link allows for downloading of files.
This can only be set when `access` is set to
`open` or `company`.
example: true
type: boolean
can_edit:
description: |-
If the shared link allows for editing of files.
This can only be set when `access` is set to
`open` or `company`.
This value can only be `true` is `can_download` is
also `true`.
example: true
type: boolean
can_preview:
description: |-
If the shared link allows for previewing of files.
This value is always `true`. For shared links on folders
this also applies to any items in the folder.
example: true
type: boolean
type: object
unshared_at:
description: |-
The timestamp at which this shared link will
expire. This field can only be set by
users with paid accounts. The value must be greater than the
current date and time.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
vanity_name:
description: |-
Defines a custom vanity name to use in the shared link URL,
for example `https://app.box.com/v/my-shared-link`.
Custom URLs should not be used when sharing sensitive content
as vanity URLs are a lot easier to guess than regular shared
links.
example: my-shared-link
minLength: 12
type: string
type: object
type: object
responses:
"200":
content:
application/json:
examples:
default:
value:
etag: "1"
id: "12345"
shared_link:
access: open
download_count: 0
download_url: https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf
effective_access: open
effective_permission: can_download
is_password_enabled: false
permissions:
can_download: true
can_edit: true
can_preview: true
preview_count: 0
unshared_at: 2020-09-21T10:34:41-07:00
url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1
vanity_name: null
vanity_url: null
type: file
schema:
$ref: "#/components/schemas/File--Full"
description: |-
Returns the base representation of a file with a new shared
link attached.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned when there is an incorrect permission combination
"401":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when the access token provided in the `Authorization` header
is not recognized or not provided.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned if the user does not have all the permissions to complete the
update.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned if the file is not found, or the user does not
have access to the file.
"405":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned if the `file_id` is not in a recognized format.
"412":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Add shared link to file
tags:
- Shared links (Files)
x-box-enable-explorer: true
x-box-sanitized: true
x-box-tag: shared_links_files
"/files/{file_id}#get_shared_link":
get:
description: Gets the information for a shared link on a file.
operationId: get_files_id#get_shared_link
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
- description: |-
Explicitly request the `shared_link` fields
to be returned for this item.
example: shared_link
in: query
name: fields
required: true
schema:
type: string
responses:
"200":
content:
application/json:
examples:
default:
value:
etag: "1"
id: "12345"
shared_link:
access: open
download_count: 0
download_url: https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf
effective_access: open
effective_permission: can_download
is_password_enabled: false
permissions:
can_download: true
can_edit: true
can_preview: true
preview_count: 0
unshared_at: 2020-09-21T10:34:41-07:00
url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1
vanity_name: null
vanity_url: null
type: file
schema:
$ref: "#/components/schemas/File--Full"
description: |-
Returns the base representation of a file with the
additional shared link information.
"401":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when the access token provided in the `Authorization` header
is not recognized or not provided.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned if the file is not found, or the user does not
have access to the file.
"405":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned if the `file_id` is not in a recognized format.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get shared link for file
tags:
- Shared links (Files)
x-box-enable-explorer: true
x-box-sanitized: true
x-box-tag: shared_links_files
"/files/{file_id}#remove_shared_link":
put:
description: Removes a shared link from a file.
operationId: put_files_id#remove_shared_link
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
- description: |-
Explicitly request the `shared_link` fields
to be returned for this item.
example: shared_link
in: query
name: fields
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
shared_link:
description: |-
By setting this value to `null`, the shared link
is removed from the file.
example: null
nullable: true
type: object
type: object
responses:
"200":
content:
application/json:
examples:
default:
value:
etag: "1"
id: "12345"
shared_link: null
type: file
schema:
$ref: "#/components/schemas/File--Full"
description: Returns a basic representation of a file, with the shared link removed.
"401":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when the access token provided in the `Authorization` header
is not recognized or not provided.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned if the user does not have all the permissions to complete the
update.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned if the file is not found, or the user does not
have access to the file.
"405":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned if the `file_id` is not in a recognized format.
"412":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Remove shared link from file
tags:
- Shared links (Files)
x-box-enable-explorer: true
x-box-sanitized: true
x-box-tag: shared_links_files
"/files/{file_id}#update_shared_link":
put:
description: Updates a shared link on a file.
operationId: put_files_id#update_shared_link
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
- description: |-
Explicitly request the `shared_link` fields
to be returned for this item.
example: shared_link
in: query
name: fields
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
shared_link:
description: The settings for the shared link to update.
properties:
access:
description: |-
The level of access for the shared link. This can be
restricted to anyone with the link (`open`), only people
within the company (`company`) and only those who
have been invited to the folder (`collaborators`).
If not set, this field defaults to the access level specified
by the enterprise admin. To create a shared link with this
default setting pass the `shared_link` object with
no `access` field, for example `{ "shared_link": {} }`.
The `company` access level is only available to paid
accounts.
enum:
- open
- company
- collaborators
example: open
type: string
password:
description: |-
The password required to access the shared link. Set the
password to `null` to remove it.
A password can only be set when `access` is set to `open`.
example: do-not-use-this-password
type: string
permissions:
properties:
can_download:
description: |-
If the shared link allows for downloading of files.
This can only be set when `access` is set to
`open` or `company`.
example: true
type: boolean
can_edit:
description: |-
If the shared link allows for editing of files.
This can only be set when `access` is set to
`open` or `company`.
This value can only be `true` is `can_download` is
also `true`.
example: true
type: boolean
can_preview:
description: |-
If the shared link allows for previewing of files.
This value is always `true`. For shared links on folders
this also applies to any items in the folder.
example: true
type: boolean
type: object
unshared_at:
description: |-
The timestamp at which this shared link will
expire. This field can only be set by
users with paid accounts. The value must be greater than the
current date and time.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
vanity_name:
description: |-
Defines a custom vanity name to use in the shared link URL,
for example `https://app.box.com/v/my-shared-link`.
Custom URLs should not be used when sharing sensitive content
as vanity URLs are a lot easier to guess than regular shared
links.
example: my-shared-link
minLength: 12
type: string
type: object
type: object
responses:
"200":
content:
application/json:
examples:
default:
value:
etag: "1"
id: "12345"
shared_link:
access: open
download_count: 0
download_url: https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf
effective_access: open
effective_permission: can_download
is_password_enabled: false
permissions:
can_download: true
can_edit: true
can_preview: true
preview_count: 0
unshared_at: 2020-09-21T10:34:41-07:00
url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1
vanity_name: null
vanity_url: null
type: file
schema:
$ref: "#/components/schemas/File--Full"
description: |-
Returns a basic representation of the file, with the updated shared
link attached.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned when there is an incorrect permission combination
"401":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when the access token provided in the `Authorization` header
is not recognized or not provided.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned if the user does not have all the permissions to complete the
update.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned if the file is not found, or the user does not
have access to the file.
"405":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned if the `file_id` is not in a recognized format.
"412":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Update shared link on file
tags:
- Shared links (Files)
x-box-enable-explorer: true
x-box-sanitized: true
x-box-tag: shared_links_files
"/files/{file_id}/collaborations":
get:
description: |-
Retrieves a list of pending and active collaborations for a
file. This returns all the users that have access to the file
or have been invited to the file.
operationId: get_files_id_collaborations
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
- description: |-
Defines the position marker at which to begin returning results. This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
in: query
name: marker
required: false
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Collaborations"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List file collaborations
tags:
- Collaborations (List)
x-box-tag: list_collaborations
"/files/{file_id}/comments":
get:
description: Retrieves a list of comments for a file.
operationId: get_files_id_comments
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
- description: |-
The offset of the item at which to begin the response.
Queries with offset parameter value
exceeding 10000 will be rejected
with a 400 response.
example: 1000
in: query
name: offset
required: false
schema:
default: 0
format: int64
type: integer
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Comments"
description: |-
Returns a collection of comment objects. If there are no
comments on this file an empty collection will be returned.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List file comments
tags:
- Comments
x-box-tag: comments
"/files/{file_id}/content":
get:
description: Returns the contents of a file in binary format.
operationId: get_files_id_content
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
- description: |-
The byte range of the content to download.
The format `bytes={start_byte}-{end_byte}` can be used to specify
what section of the file to download.
example: bytes=0-1024
in: header
name: range
required: false
schema:
type: string
- description: |-
The URL, and optional password, for the shared link of this item.
This header can be used to access items that have not been
explicitly shared with a user.
Use the format `shared_link=[link]` or if a password is required then
use `shared_link=[link]&shared_link_password=[password]`.
This header can be used on the file or folder shared, as well as on any files
or folders nested within the item.
example: shared_link=[link]&shared_link_password=[password]
in: header
name: boxapi
required: false
schema:
type: string
- description: The file version to download
example: "4"
in: query
name: version
required: false
schema:
type: string
- description: |-
An optional access token that can be used to pre-authenticate this request, which means that a download link can be shared with a browser or a third party service without them needing to know how to handle the authentication.
When using this parameter, please make sure that the access token is sufficiently scoped down to only allow read access to that file and no other files or folders.
example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ
in: query
name: access_token
required: false
schema:
type: string
responses:
"202":
description: |-
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.
headers:
Retry-After:
description: The time in seconds after which to retry the download
schema:
type: integer
"302":
description: |-
If the file is available to be downloaded 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 in order to actually download the file.
headers:
Location:
description: A pointer to the download URL
schema:
format: url
type: string
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Download file
tags:
- Downloads
x-box-tag: downloads
post:
description: |-
Update a file's content. For file sizes over 50MB we recommend
using the Chunk Upload APIs.
# Request body order
The `attributes` part of the body must come **before** the
`file` part. Requests that do not follow this format when
uploading the file will receive a HTTP `400` error with a
`metadata_after_file_contents` error code.
operationId: post_files_id_content
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
- description: |-
Ensures this item hasn't recently changed before
making changes.
Pass in the item's last observed `etag` value
into this header and the endpoint will fail
with a `412 Precondition Failed` if it
has changed since.
example: "1"
in: header
name: if-match
required: false
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
- description: |-
An optional header containing the SHA1 hash of the file to
ensure that the file was not corrupted in transit.
example: 134b65991ed521fcfe4724b7d814ab8ded5185dc
in: header
name: content-md5
required: false
schema:
type: string
requestBody:
content:
multipart/form-data:
schema:
properties:
attributes:
description: |-
The additional attributes of the file being uploaded. Mainly the
name and the parent folder. These attributes are part of the multi
part request body and are in JSON format.
The `attributes` part of the body must come **before** the
`file` part. Requests that do not follow this format when
uploading the file will receive a HTTP `400` error with a
`metadata_after_file_contents` error code.
properties:
content_modified_at:
description: |-
Defines the time the file was last modified at.
If not set, the upload time will be used.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
name:
description: |-
An optional new name for the file. If specified, the file
will be renamed when the new version is uploaded.
example: Photo 2.0.png
type: string
required:
- name
type: object
file:
description: |-
The content of the file to upload to Box.
The `attributes` part of the body must come **before** the
`file` part. Requests that do not follow this format when
uploading the file will receive a HTTP `400` error with a
`metadata_after_file_contents` error code.
format: binary
type: string
required:
- attributes
- file
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Files"
description: Returns the new file object in a list.
"412":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
servers:
- description: Server for file uploads
url: https://upload.box.com/api/2.0
summary: Upload file version
tags:
- Uploads
x-box-tag: uploads
"/files/{file_id}/copy":
post:
description: Creates a copy of a file.
operationId: post_files_id_copy
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
requestBody:
content:
application/json:
schema:
nullable: false
properties:
name:
description: |-
An optional new name for the copied file.
There are some restrictions to the file name. Names containing
non-printable ASCII characters, forward and backward slashes
(`/`, `\`), and protected names like `.` and `..` are
automatically sanitized by removing the non-allowed
characters.
example: FileCopy.txt
maxLength: 255
type: string
parent:
description: The destination folder to copy the file to.
properties:
id:
description: The ID of folder to copy the file to.
example: "0"
type: string
required:
- id
type: object
version:
description: An optional ID of the specific file version to copy.
example: "0"
type: string
required:
- parent
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/File--Full"
description: |-
Returns a new file object representing the copied file.
Not all available fields are returned by default. Use the
[fields](#param-fields) query parameter to explicitly request
any specific fields.
"304":
description: |-
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":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if some of the parameters are missing or
not valid.
* `bad_request` when a parameter is missing.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
* `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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Copy file
tags:
- Files
x-box-enable-explorer: true
x-box-sanitized: true
x-box-tag: files
"/files/{file_id}/metadata":
get:
description: Retrieves all metadata for a given file.
operationId: get_files_id_metadata
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Metadatas"
description: |-
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.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned when the request parameters are not valid.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned when the user does not have access to the file.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List metadata instances on file
tags:
- Metadata instances (Files)
x-box-sanitized: true
x-box-tag: file_metadata
"/files/{file_id}/metadata/enterprise/securityClassification-6VMVochwUWo":
delete:
description: |-
Removes any classifications from a file.
This API can also be called by including the enterprise ID in the
URL explicitly, for example
`/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`.
operationId: delete_files_id_metadata_enterprise_securityClassification-6VMVochwUWo
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
responses:
"204":
description: |-
Returns an empty response when the classification is
successfully deleted.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned when the request parameters are not valid.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"405":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned when the method was not allowed.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Remove classification from file
tags:
- Classifications on files
x-box-sanitized: true
x-box-tag: file_classifications
get:
description: |-
Retrieves the classification metadata instance that
has been applied to a file.
This API can also be called by including the enterprise ID in the
URL explicitly, for example
`/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`.
operationId: get_files_id_metadata_enterprise_securityClassification-6VMVochwUWo
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/Classification"
description: |-
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.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned when the request parameters are not valid.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"405":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned when the method was not allowed.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get classification on file
tags:
- Classifications on files
x-box-sanitized: true
x-box-tag: file_classifications
post:
description: |-
Adds a classification to a file by specifying the label of the
classification to add.
This API can also be called by including the enterprise ID in the
URL explicitly, for example
`/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`.
operationId: post_files_id_metadata_enterprise_securityClassification-6VMVochwUWo
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
Box__Security__Classification__Key:
description: |-
The name of the classification to apply to this file.
To list the available classifications in an enterprise,
use the classification API to retrieve the
[classification template](e://get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema)
which lists all available classification keys.
example: Sensitive
type: string
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/Classification"
description: |-
Returns the classification template instance
that was applied to the file.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error when the request body is not valid.
* `schema_validation_failed` - The request body contains a value for a 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.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Add classification to file
tags:
- Classifications on files
x-box-sanitized: true
x-box-tag: file_classifications
put:
description: |-
Updates a classification on a file.
The classification can only be updated if a classification has already been
applied to the file before. When editing classifications, only values are
defined for the enterprise will be accepted.
operationId: put_files_id_metadata_enterprise_securityClassification-6VMVochwUWo
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
requestBody:
content:
application/json-patch+json:
schema:
description: |-
A list containing the one change to make, to
update the classification label.
items:
description: |-
The operation to perform on the classification
metadata template instance. In this case, it use
used to replace the value stored for the
`Box__Security__Classification__Key` field with a new
value.
properties:
op:
description: "`replace`"
enum:
- replace
example: replace
type: string
path:
description: "`/Box__Security__Classification__Key`"
enum:
- /Box__Security__Classification__Key
example: /Box__Security__Classification__Key
type: string
value:
description: |-
The name of the classification to apply to this file.
To list the available classifications in an enterprise,
use the classification API to retrieve the
[classification template](e://get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema)
which lists all available classification keys.
example: Sensitive
type: string
type: object
type: array
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Classification"
description: Returns the updated classification metadata template instance.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"500":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error in some edge cases when the request body is not a valid
array of JSON Patch items.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Update classification on file
tags:
- Classifications on files
x-box-sanitized: true
x-box-tag: file_classifications
"/files/{file_id}/metadata/global/boxSkillsCards":
delete:
description: Removes any Box Skills cards metadata from a file.
operationId: delete_files_id_metadata_global_boxSkillsCards
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
responses:
"204":
description: |-
Returns an empty response when the cards are
successfully deleted.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"405":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned when the method was not allowed.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Remove Box Skill cards from file
tags:
- Skills
x-box-sanitized: true
x-box-tag: skills
get:
description: List the Box Skills metadata cards that are attached to a file.
operationId: get_files_id_metadata_global_boxSkillsCards
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/SkillCardsMetadata"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List Box Skill cards on file
tags:
- Skills
x-box-tag: skills
post:
description: Applies one or more Box Skills metadata cards to a file.
operationId: post_files_id_metadata_global_boxSkillsCards
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
cards:
description: A list of Box Skill cards to apply to this file.
items:
oneOf:
- $ref: "#/components/schemas/KeywordSkillCard"
- $ref: "#/components/schemas/TimelineSkillCard"
- $ref: "#/components/schemas/TranscriptSkillCard"
- $ref: "#/components/schemas/StatusSkillCard"
type: array
required:
- cards
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/SkillCardsMetadata"
description: |-
Returns the instance of the template that was applied to the file,
including the data that was applied to the template.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error when the request body is not valid.
* `schema_validation_failed` - The request body contains a value for a 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.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Create Box Skill cards on file
tags:
- Skills
x-box-tag: skills
put:
description: Updates one or more Box Skills metadata cards to a file.
operationId: put_files_id_metadata_global_boxSkillsCards
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
requestBody:
content:
application/json-patch+json:
schema:
description: |-
A [JSON-Patch](https://tools.ietf.org/html/rfc6902)
specification for the changes to make to the metadata
template.
The changes are represented as a JSON array of
operation objects.
items:
description: An operation that replaces an existing card.
properties:
op:
description: "`replace`"
enum:
- replace
example: replace
type: string
path:
description: |-
The JSON Path that represents the card to replace. In most cases
this will be in the format `/cards/{index}` where `index` is the
zero-indexed position of the card in the list of cards.
example: /cards/0
type: string
value:
allOf:
- oneOf:
- $ref: "#/components/schemas/KeywordSkillCard"
- $ref: "#/components/schemas/TimelineSkillCard"
- $ref: "#/components/schemas/TranscriptSkillCard"
- $ref: "#/components/schemas/StatusSkillCard"
- description: |-
The card to insert into the list of cards at the
position defined by `path`.
type: object
type: array
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/SkillCardsMetadata"
description: |-
Returns the updated metadata template, with the
custom template data included.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: The requested file could not be found
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Update Box Skill cards on file
tags:
- Skills
x-box-tag: skills
"/files/{file_id}/metadata/{scope}/{template_key}":
delete:
description: Deletes a piece of file metadata.
operationId: delete_files_id_metadata_id_id
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
- description: The scope of the metadata template
example: global
in: path
name: scope
required: true
schema:
enum:
- global
- enterprise
type: string
- description: The name of the metadata template
example: properties
in: path
name: template_key
required: true
schema:
type: string
responses:
"204":
description: |-
Returns an empty response when the metadata is
successfully deleted.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when the request parameters are not valid. This may happen of the
`scope` is not valid.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"405":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned when the method was not allowed.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Remove metadata instance from file
tags:
- Metadata instances (Files)
x-box-sanitized: true
x-box-tag: file_metadata
get:
description: |-
Retrieves the instance of a metadata template that has been applied to a
file.
operationId: get_files_id_metadata_id_id
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
- description: The scope of the metadata template
example: global
in: path
name: scope
required: true
schema:
enum:
- global
- enterprise
type: string
- description: The name of the metadata template
example: properties
in: path
name: template_key
required: true
schema:
type: string
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/Metadata"
description: |-
An instance of the metadata template that includes
additional "key:value" pairs defined by the user or
an application.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned when the request parameters are not valid.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"405":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned when the method was not allowed.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get metadata instance on file
tags:
- Metadata instances (Files)
x-box-sanitized: true
x-box-tag: file_metadata
post:
description: |-
Applies an instance of a metadata template to a file.
In most cases only values that are present in the metadata template
will be accepted, except for the `global.properties` template which accepts
any key-value pair.
operationId: post_files_id_metadata_id_id
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
- description: The scope of the metadata template
example: global
in: path
name: scope
required: true
schema:
enum:
- global
- enterprise
type: string
- description: The name of the metadata template
example: properties
in: path
name: template_key
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
additionalProperties:
description: |-
A value for each of the fields that are present on the metadata
template.
For the `global.properties` template this can be an a list of zero
or more fields, as this template allows for any generic key-value
pairs to be stored on the template.
example: Aaron Levie
type: string
x-box-example-key: name
example:
name: Aaron Levie
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/Metadata"
description: |-
Returns the instance of the template that was applied to the file,
including the data that was applied to the template.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error when the request body is not valid.
* `schema_validation_failed` - The request body contains a value for a 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.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Create metadata instance on file
tags:
- Metadata instances (Files)
x-box-sanitized: true
x-box-tag: file_metadata
put:
description: |-
Updates a piece of metadata on a file.
The metadata instance can only be updated if the template has already been
applied to the file before. When editing metadata, only values that match
the metadata template schema will be accepted.
The update is applied atomically. If any errors occur during the
application of the operations, the metadata instance will not be changed.
operationId: put_files_id_metadata_id_id
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
- description: The scope of the metadata template
example: global
in: path
name: scope
required: true
schema:
enum:
- global
- enterprise
type: string
- description: The name of the metadata template
example: properties
in: path
name: template_key
required: true
schema:
type: string
requestBody:
content:
application/json-patch+json:
schema:
description: |-
A [JSON-Patch](https://tools.ietf.org/html/rfc6902)
specification for the changes to make to the metadata
instance.
The changes are represented as a JSON array of
operation objects.
items:
description: |-
A [JSON-Patch](https://tools.ietf.org/html/rfc6902) operation for a
change to make to the metadata instance.
properties:
from:
description: |-
The location in the metadata JSON object to move or copy a value
from. Required for `move` or `copy` operations and must be in the
format of a [JSON-Pointer](https://tools.ietf.org/html/rfc6901).
example: /nextState
type: string
op:
description: |-
The type of change to perform on the template. Some
of these are hazardous as they will change existing templates.
enum:
- add
- replace
- remove
- test
- move
- copy
example: add
type: string
path:
description: |-
The location in the metadata JSON object
to apply the changes to, in the format of a
[JSON-Pointer](https://tools.ietf.org/html/rfc6901).
The path must always be prefixed with a `/` to represent the root
of the template. The characters `~` and `/` are reserved
characters and must be escaped in the key.
example: /currentState
type: string
value:
description: |-
The value to be set or tested.
Required for `add`, `replace`, and `test` operations. For `add`,
if the value exists already the previous value will be overwritten
by the new value. For `replace`, the value must exist before
replacing.
For `test`, the existing value at the `path` location must match
the specified value.
example: reviewed
type: string
title: A metadata instance update operation
type: object
type: array
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Metadata"
description: |-
Returns the updated metadata template instance, with the
custom template data included.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"500":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error in some edge cases when the request body is not a valid
array of JSON Patch items.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Update metadata instance on file
tags:
- Metadata instances (Files)
x-box-sanitized: true
x-box-tag: file_metadata
"/files/{file_id}/tasks":
get:
description: |-
Retrieves a list of all the tasks for a file. This
endpoint does not support pagination.
operationId: get_files_id_tasks
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Tasks"
description: |-
Returns a list of tasks on a file.
If there are no tasks on this file an empty collection is returned
instead.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error when the file could not be found or the user does not
have access to the file.
"405":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error when the `file_id` was not provided.
"500":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error when an attempt was made to retrieve tasks for the file
with ID `0`.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List tasks on file
tags:
- Tasks
x-box-sanitized: true
x-box-tag: tasks
"/files/{file_id}/thumbnail.{extension}":
get:
description: |-
Retrieves a thumbnail, or smaller image representation, of a file.
Sizes of `32x32`,`64x64`, `128x128`, and `256x256` can be returned in
the `.png` format and sizes of `32x32`, `160x160`, and `320x320`
can be returned in the `.jpg` format.
Thumbnails can be generated for the image and video file formats listed
[found on our community site][1].
[1]: https://community.box.com/t5/Migrating-and-Previewing-Content/File-Types-and-Fonts-Supported-in-Box-Content-Preview/ta-p/327
operationId: get_files_id_thumbnail_id
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
- description: The file format for the thumbnail
example: png
in: path
name: extension
required: true
schema:
enum:
- png
- jpg
type: string
- description: The minimum height of the thumbnail
example: 32
in: query
name: min_height
schema:
maximum: 320
minimum: 32
type: integer
- description: The minimum width of the thumbnail
example: 32
in: query
name: min_width
schema:
maximum: 320
minimum: 32
type: integer
- description: The maximum height of the thumbnail
example: 320
in: query
name: max_height
required: false
schema:
maximum: 320
minimum: 32
type: integer
- description: The maximum width of the thumbnail
example: 320
in: query
name: max_width
required: false
schema:
maximum: 320
minimum: 32
type: integer
responses:
"200":
content:
image/jpg:
schema:
description: The thumbnail
format: binary
type: string
image/png:
schema:
description: The thumbnail
format: binary
type: string
description: |-
When a thumbnail can be created the thumbnail data will be
returned in the body of the response.
"202":
description: |-
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.
headers:
Location:
description: |-
A pointer to a placeholder graphic that can be used until the
thumbnail has been generated.
schema:
format: url
type: string
Retry-After:
description: |-
The time in seconds after which the thumbnail will be available.
Your application only attempt to get the thumbnail again after
this time.
schema:
format: int64
type: integer
"302":
description: |-
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.
headers:
Location:
description: |-
A pointer to a placeholder graphic that can be used for this
file type.
schema:
format: url
type: string
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when the access token provided in the `Authorization` header
is not recognized or not provided.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get file thumbnail
tags:
- Files
x-box-tag: files
"/files/{file_id}/trash":
delete:
description: |-
Permanently deletes a file that is in the trash.
This action cannot be undone.
operationId: delete_files_id_trash
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
responses:
"204":
description: |-
Returns an empty response when the file was
permanently deleted.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if the file is not in the trash.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Permanently remove file
tags:
- Trashed files
x-box-tag: trashed_files
get:
description: |-
Retrieves a file that has been moved to the trash.
Please note that only if the file itself has been moved to the
trash can it be retrieved with this API call. If instead one of
its parent folders was moved to the trash, only that folder
can be inspected using the
[`GET /folders/:id/trash`](e://get_folders_id_trash) API.
To list all items that have been moved to the trash, please
use the [`GET /folders/trash/items`](e://get-folders-trash-items/)
API.
operationId: get_files_id_trash
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/TrashFile"
description: |-
Returns the file that was trashed,
including information about when the it
was moved to the trash.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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`](e://get_folders_id_trash) API.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get trashed file
tags:
- Trashed files
x-box-tag: trashed_files
"/files/{file_id}/upload_sessions":
post:
description: Creates an upload session for an existing file.
operationId: post_files_id_upload_sessions
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
file_name:
description: The optional new name of new file
example: Project.mov
type: string
file_size:
description: The total number of bytes of the file to be uploaded
example: 104857600
format: int64
type: integer
required:
- file_size
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/UploadSession"
description: Returns a new upload session.
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if the file already exists,
or if the account has run out of disk space.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
servers:
- description: Server for file uploads
url: https://upload.box.com/api/2.0
summary: Create upload session for existing file
tags:
- Uploads (Chunked)
x-box-tag: chunked_uploads
"/files/{file_id}/versions":
get:
description: |-
Retrieve a list of the past versions for a file.
Versions are only tracked by Box users with premium accounts. To fetch the ID
of the current version of a file, use the `GET /file/:id` API.
operationId: get_files_id_versions
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
- description: |-
The offset of the item at which to begin the response.
Queries with offset parameter value
exceeding 10000 will be rejected
with a 400 response.
example: 1000
in: query
name: offset
required: false
schema:
default: 0
format: int64
type: integer
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/FileVersions"
description: Returns an array of past versions for this file.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List all file versions
tags:
- File versions
x-box-tag: file_versions
"/files/{file_id}/versions/current":
post:
description: |-
Promote a specific version of a file.
If previous versions exist, this method can be used to
promote one of the older versions to the top of the version history.
This creates a new copy of the old version and puts it at the
top of the versions history. The file will have the exact same contents
as the older version, with the the same hash digest, `etag`, and
name as the original.
Other properties such as comments do not get updated to their
former values.
Don't use this endpoint to restore Box Notes,
as it works with file formats such as PDF, DOC,
PPTX or similar.
operationId: post_files_id_versions_current
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
requestBody:
content:
application/json:
schema:
description: The file version to promote
properties:
id:
description: The file version ID
example: "11446498"
type: string
type:
description: The type to promote
enum:
- file_version
example: file_version
type: string
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/FileVersion--Full"
description: Returns a newly created file version object.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Promote file version
tags:
- File versions
x-box-tag: file_versions
"/files/{file_id}/versions/{file_version_id}":
delete:
description: |-
Move a file version to the trash.
Versions are only tracked for Box users with premium accounts.
operationId: delete_files_id_versions_id
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
- description: The ID of the file version
example: "1234"
in: path
name: file_version_id
required: true
schema:
type: string
- description: |-
Ensures this item hasn't recently changed before
making changes.
Pass in the item's last observed `etag` value
into this header and the endpoint will fail
with a `412 Precondition Failed` if it
has changed since.
example: "1"
in: header
name: if-match
required: false
schema:
type: string
responses:
"204":
description: |-
Returns an empty response when the file has been successfully
deleted.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Remove file version
tags:
- File versions
x-box-tag: file_versions
get:
description: |-
Retrieve a specific version of a file.
Versions are only tracked for Box users with premium accounts.
operationId: get_files_id_versions_id
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
- description: The ID of the file version
example: "1234"
in: path
name: file_version_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/FileVersion--Full"
description: |-
Returns a specific version of a file.
Not all available fields are returned by default. Use the
[fields](#param-fields) query parameter to explicitly request
any specific fields.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get file version
tags:
- File versions
x-box-tag: file_versions
put:
description: |-
Restores a specific version of a file after it was deleted.
Don't use this endpoint to restore Box Notes,
as it works with file formats such as PDF, DOC,
PPTX or similar.
operationId: put_files_id_versions_id
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
- description: The ID of the file version
example: "1234"
in: path
name: file_version_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
description: |-
The file version to be
restored
properties:
trashed_at:
description: |-
Set this to `null` to clear
the date and restore the file.
example: "null"
type: string
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/FileVersion--Full"
description: Returns a restored file version object.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Restore file version
tags:
- File versions
x-box-tag: file_versions
"/files/{file_id}/watermark":
delete:
description: Removes the watermark from a file.
operationId: delete_files_id_watermark
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
responses:
"204":
description: Removes the watermark and returns an empty response.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if the file did not have
a watermark applied to it.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Remove watermark from file
tags:
- Watermarks (Files)
x-box-tag: file_watermarks
get:
description: Retrieve the watermark for a file.
operationId: get_files_id_watermark
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Watermark"
description: |-
Returns an object containing information about the
watermark associated for to this file.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if the file does not have a watermark applied.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get watermark on file
tags:
- Watermarks (Files)
x-box-tag: file_watermarks
put:
description: Applies or update a watermark on a file.
operationId: put_files_id_watermark
parameters:
- description: |-
The unique identifier that represents a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
in: path
name: file_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
watermark:
description: The watermark to imprint on the file
properties:
imprint:
description: |-
The type of watermark to apply.
Currently only supports one option.
enum:
- default
example: default
type: string
required:
- imprint
type: object
required:
- watermark
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Watermark"
description: |-
Returns an updated watermark if a watermark already
existed on this file.
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/Watermark"
description: |-
Returns a new watermark if no watermark existed on
this file yet.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Apply watermark to file
tags:
- Watermarks (Files)
x-box-tag: file_watermarks
/folder_locks:
get:
description: |-
Retrieves folder lock details for a given folder.
You must be authenticated as the owner or co-owner of the folder to
use this endpoint.
operationId: get_folder_locks
parameters:
- description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting this folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folder/123`
the `folder_id` is `123`.
The root folder of a Box account is
always represented by the ID `0`.
example: "12345"
in: query
name: folder_id
required: true
schema:
nullable: false
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/FolderLocks"
description: |-
Returns details for all folder locks applied to the folder, including the
lock type and user that applied the lock.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when the access token provided in the `Authorization` header
is not recognized or not provided.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned if the folder is not found, or the user does not
have access to the folder.
"405":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned if the `folder_id` is not in a recognized format.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List folder locks
tags:
- Folder Locks
x-box-enable-explorer: true
x-box-sanitized: true
x-box-tag: folder_locks
post:
description: |-
Creates a folder lock on a folder, preventing it from being moved and/or
deleted.
You must be authenticated as the owner or co-owner of the folder to
use this endpoint.
operationId: post_folder_locks
requestBody:
content:
application/json:
schema:
properties:
folder:
description: The folder to apply the lock to.
properties:
id:
description: The ID of the folder.
example: "1234567890"
type: string
type:
description: |-
The content type the lock is being applied to. Only `folder`
is supported.
example: folder
type: string
required:
- type
- id
type: object
locked_operations:
description: |-
The operations to lock for the folder. If `locked_operations` is
included in the request, both `move` and `delete` must also be
included and both set to `true`.
properties:
delete:
description: Whether deleting the folder should be locked.
example: true
type: boolean
move:
description: Whether moving the folder should be locked.
example: true
type: boolean
required:
- move
- delete
type: object
required:
- folder
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/FolderLock"
description: |-
Returns the instance of the folder lock that was applied to the folder,
including the user that applied the lock and the operations set.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Create folder lock
tags:
- Folder Locks
x-box-enable-explorer: false
x-box-sanitized: true
x-box-tag: folder_locks
"/folder_locks/{folder_lock_id}":
delete:
description: |-
Deletes a folder lock on a given folder.
You must be authenticated as the owner or co-owner of the folder to
use this endpoint.
operationId: delete_folder_locks_id
parameters:
- description: The ID of the folder lock.
example: "12345"
in: path
name: folder_lock_id
required: true
schema:
nullable: false
type: string
responses:
"204":
description: Returns an empty response when the folder lock is successfully deleted.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Delete folder lock
tags:
- Folder Locks
x-box-sanitized: true
x-box-tag: folder_locks
/folders:
post:
description: Creates a new empty folder within the specified parent folder.
operationId: post_folders
parameters:
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
requestBody:
content:
application/json:
schema:
properties:
folder_upload_email:
allOf:
- description: The Write Folder Upload Email object
properties:
access:
description: |-
When this parameter has been set, users can email files
to the email address that has been automatically
created for this folder.
To create an email address, set this property either when
creating or updating the folder.
When set to `collaborators`, only emails from registered email
addresses for collaborators will be accepted. This includes
any email aliases a user might have registered.
When set to `open` it will accept emails from any email
address.
enum:
- open
- collaborators
example: open
nullable: false
type: string
title: Folder upload email
type: object
- description: |-
Setting this object enables the upload email address.
This email address can be used by users to directly
upload files directly to the folder via email.
name:
description: |-
The name for the new folder.
There are some restrictions to the file name. Names containing
non-printable ASCII characters, forward and backward slashes
(`/`, `\`), as well as names with trailing spaces are
prohibited.
Additionally, the names `.` and `..` are
not allowed either.
example: New Folder
maxLength: 255
minLength: 1
type: string
parent:
description: The parent folder to create the new folder within.
properties:
id:
description: The ID of parent folder
example: "0"
type: string
required:
- id
type: object
sync_state:
description: |-
Specifies whether a folder should be synced to a
user's device or not. This is used by Box Sync
(discontinued) and is not used by Box Drive.
enum:
- synced
- not_synced
- partially_synced
example: synced
nullable: false
type: string
required:
- name
- parent
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/Folder--Full"
description: |-
Returns a folder object.
Not all available fields are returned by default. Use the
[fields](#param-fields) query parameter to explicitly request
any specific fields.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
* `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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Create folder
tags:
- Folders
x-box-enable-explorer: true
x-box-tag: folders
/folders/trash/items:
get:
description: |-
Retrieves the files and folders that have been moved
to the trash.
Any attribute in the full files or folders objects can be passed
in with the `fields` parameter to retrieve those specific
attributes that are not returned by default.
This endpoint defaults to use offset-based pagination, yet also supports
marker-based pagination using the `marker` parameter.
operationId: get_folders_trash_items
parameters:
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
- description: |-
The offset of the item at which to begin the response.
Queries with offset parameter value
exceeding 10000 will be rejected
with a 400 response.
example: 1000
in: query
name: offset
required: false
schema:
default: 0
format: int64
type: integer
- description: |-
Specifies whether to use marker-based pagination instead of
offset-based pagination. Only one pagination method can
be used at a time.
By setting this value to true, the API will return a `marker` field
that can be passed as a parameter to this endpoint to get the next
page of the response.
example: true
in: query
name: usemarker
required: false
schema:
type: boolean
- description: |-
Defines the position marker at which to begin returning results. This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
in: query
name: marker
required: false
schema:
type: string
- description: |-
The direction to sort results in. This can be either in alphabetical ascending
(`ASC`) or descending (`DESC`) order.
example: ASC
in: query
name: direction
required: false
schema:
enum:
- ASC
- DESC
type: string
- description: |-
Defines the **second** attribute by which items
are sorted.
Items are always sorted by their `type` first, with
folders listed before files, and files listed
before web links.
This parameter is not supported when using marker-based pagination.
example: id
in: query
name: sort
required: false
schema:
enum:
- id
- name
- date
- size
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Items"
description: Returns a list of items that have been deleted
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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`.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List trashed items
tags:
- Trashed items
x-box-tag: trashed_items
"/folders/{folder_id}":
delete:
description: |-
Deletes a folder, either permanently or by moving it to
the trash.
operationId: delete_folders_id
parameters:
- description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting this folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folder/123`
the `folder_id` is `123`.
The root folder of a Box account is
always represented by the ID `0`.
example: "12345"
in: path
name: folder_id
required: true
schema:
nullable: false
type: string
- description: |-
Ensures this item hasn't recently changed before
making changes.
Pass in the item's last observed `etag` value
into this header and the endpoint will fail
with a `412 Precondition Failed` if it
has changed since.
example: "1"
in: header
name: if-match
required: false
schema:
type: string
- description: |-
Delete a folder that is not empty by recursively deleting the
folder and all of its content.
example: true
in: query
name: recursive
required: false
schema:
type: boolean
responses:
"204":
description: |-
Returns an empty response when the folder is successfully deleted
or moved to the trash.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
* `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.
"412":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"503":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error when the operation takes longer
than 60 seconds. The operation will continue after
this response has been returned.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Delete folder
tags:
- Folders
x-box-sanitized: true
x-box-tag: folders
get:
description: |-
Retrieves details for a folder, including the first 100 entries
in the folder.
To fetch more items within the folder, please use the
[Get items in a folder](#get-folders-id-items) endpoint.
operationId: get_folders_id
parameters:
- description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting this folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folder/123`
the `folder_id` is `123`.
The root folder of a Box account is
always represented by the ID `0`.
example: "12345"
in: path
name: folder_id
required: true
schema:
nullable: false
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
Additionally this field can be used to query any metadata
applied to the file by specifying the `metadata` field as well
as the scope and key of the template to retrieve, for example
`?field=metadata.enterprise_12345.contractTemplate`.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
- description: |-
Ensures an item is only returned if it has changed.
Pass in the item's last observed `etag` value
into this header and the endpoint will fail
with a `304 Not Modified` if the item has not
changed since.
example: "1"
in: header
name: if-none-match
required: false
schema:
type: string
- description: |-
The URL, and optional password, for the shared link of this item.
This header can be used to access items that have not been
explicitly shared with a user.
Use the format `shared_link=[link]` or if a password is required then
use `shared_link=[link]&shared_link_password=[password]`.
This header can be used on the file or folder shared, as well as on any files
or folders nested within the item.
example: shared_link=[link]&shared_link_password=[password]
in: header
name: boxapi
required: false
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Folder--Full"
description: |-
Returns a folder, including the first 100 entries in the folder.
To fetch more items within the folder, please use the
[Get items in a folder](#get-folders-id-items) endpoint.
Not all available fields are returned by default. Use the
[fields](#param-fields) query parameter to explicitly request
any specific fields.
"304":
description: |-
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":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when the access token provided in the `Authorization` header
is not recognized or not provided.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned if the folder is not found, or the user does not
have access to the folder.
"405":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned if the `folder_id` is not in a recognized format.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get folder information
tags:
- Folders
x-box-enable-explorer: true
x-box-sanitized: true
x-box-tag: folders
post:
description: |-
Restores a folder that has been moved to the trash.
An optional new parent ID can be provided to restore the folder to in case the
original folder has been deleted.
# Folder locking
During this operation, part of the file tree will be locked, mainly
the source folder and all of its descendants, as well as the destination
folder.
For the duration of the operation, no other move, copy, delete, or restore
operation can performed on any of the locked folders.
operationId: post_folders_id
parameters:
- description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting this folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folder/123`
the `folder_id` is `123`.
The root folder of a Box account is
always represented by the ID `0`.
example: "12345"
in: path
name: folder_id
required: true
schema:
nullable: false
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
requestBody:
content:
application/json:
schema:
properties:
name:
description: An optional new name for the folder.
example: Restored Photos
type: string
parent:
allOf:
- description: The parent for this item
properties:
id:
description: The ID of parent item
example: "123"
type: string
type: object
- description: |-
Specifies an optional ID of a folder to restore the folder
to when the original folder no longer exists.
Please be aware that this ID will only be used if the original
folder no longer exists. Use this ID to provide a fallback
location to restore the folder to if the original location
has been deleted.
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/TrashFolderRestored"
description: Returns a folder object when the folder has been restored.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if the folder is not in the trash.
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
* 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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Restore folder
tags:
- Trashed folders
x-box-tag: trashed_folders
put:
description: |-
Updates a folder. This can be also be used to move the folder,
create shared links, update collaborations, and more.
operationId: put_folders_id
parameters:
- description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting this folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folder/123`
the `folder_id` is `123`.
The root folder of a Box account is
always represented by the ID `0`.
example: "12345"
in: path
name: folder_id
required: true
schema:
nullable: false
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
- description: |-
Ensures this item hasn't recently changed before
making changes.
Pass in the item's last observed `etag` value
into this header and the endpoint will fail
with a `412 Precondition Failed` if it
has changed since.
example: "1"
in: header
name: if-match
required: false
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
can_non_owners_invite:
description: |-
Specifies if users who are not the owner
of the folder can invite new collaborators to the folder.
example: true
type: boolean
can_non_owners_view_collaborators:
description: |-
Restricts collaborators who are not the owner of
this folder from viewing other collaborations on
this folder.
It also restricts non-owners from inviting new
collaborators.
When setting this field to `false`, it is required
to also set `can_non_owners_invite_collaborators` to
`false` if it has not already been set.
example: true
type: boolean
collections:
description: |-
An array of collections to make this folder
a member of. Currently
we only support the `favorites` collection.
To get the ID for a collection, use the
[List all collections][1] endpoint.
Passing an empty array `[]` or `null` will remove
the folder from all collections.
[1]: ../advanced-files-and-folders/#get-collections
items:
description: The bare basic reference for an object
properties:
id:
description: The unique identifier for this object
example: "11446498"
type: string
type:
description: The type for this object
example: file
type: string
title: Reference
type: object
type: array
description:
description: The optional description of this folder
example: Legal contracts for the new ACME deal
maxLength: 256
nullable: false
type: string
folder_upload_email:
allOf:
- description: The Write Folder Upload Email object
properties:
access:
description: |-
When this parameter has been set, users can email files
to the email address that has been automatically
created for this folder.
To create an email address, set this property either when
creating or updating the folder.
When set to `collaborators`, only emails from registered email
addresses for collaborators will be accepted. This includes
any email aliases a user might have registered.
When set to `open` it will accept emails from any email
address.
enum:
- open
- collaborators
example: open
nullable: false
type: string
title: Folder upload email
type: object
- description: |-
Setting this object enables the upload email address.
This email address can be used by users to directly
upload files directly to the folder via email.
Setting the value to `null` will disable the email address.
is_collaboration_restricted_to_enterprise:
description: |-
Specifies if new invites to this folder are restricted to users
within the enterprise. This does not affect existing
collaborations.
example: true
type: boolean
name:
description: The optional new name for this folder.
example: New Folder
type: string
parent:
description: |-
The parent folder for this folder. Use this to move
the folder or to restore it out of the trash.
properties:
id:
description: The ID of the new parent folder
example: "0"
type: string
type: object
shared_link:
allOf:
- description: |-
Defines a shared link for an item. Set this to `null` to remove
the shared link.
properties:
access:
description: |-
The level of access for the shared link. This can be
restricted to anyone with the link (`open`), only people
within the company (`company`) and only those who
have been invited to the folder (`collaborators`).
If not set, this field defaults to the access level specified
by the enterprise admin. To create a shared link with this
default setting pass the `shared_link` object with
no `access` field, for example `{ "shared_link": {} }`.
The `company` access level is only available to paid
accounts.
enum:
- open
- company
- collaborators
example: open
type: string
password:
description: |-
The password required to access the shared link. Set the
password to `null` to remove it.
A password can only be set when `access` is set to `open`.
example: do-not-use-this-password
type: string
permissions:
properties:
can_download:
description: |-
If the shared link allows for downloading of files.
This can only be set when `access` is set to
`open` or `company`.
example: true
type: boolean
type: object
unshared_at:
description: |-
The timestamp at which this shared link will
expire. This field can only be set by
users with paid accounts.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
vanity_name:
description: |-
Defines a custom vanity name to use in the shared link URL,
for example `https://app.box.com/v/my-shared-link`.
Custom URLs should not be used when sharing sensitive content
as vanity URLs are a lot easier to guess than regular shared links.
example: my-shared-link
type: string
type: object
- description: Enables the creation of a shared link for a folder.
sync_state:
description: |-
Specifies whether a folder should be synced to a
user's device or not. This is used by Box Sync
(discontinued) and is not used by Box Drive.
enum:
- synced
- not_synced
- partially_synced
example: synced
nullable: false
type: string
tags:
description: |-
The tags for this item. These tags are shown in
the Box web app and mobile apps next to an item.
To add or remove a tag, retrieve the item's current tags,
modify them, and then update this field.
There is a limit of 100 tags per item, and 10,000
unique tags per enterprise.
example:
- approved
items:
type: string
maxItems: 100
minItems: 1
type: array
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Folder--Full"
description: |-
Returns a folder object for the updated folder
Not all available fields are returned by default. Use the
[fields](#param-fields) query parameter to explicitly request
any specific fields.
This call will return synchronously. This holds true even when
moving folders with a large a large number of items in all of its
descendants. For very large folders, this means the call could
take minutes or hours to return.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
* `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.
"412":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"503":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error when the operation takes longer
than 60 seconds. The operation will continue after
this response has been returned.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Update folder
tags:
- Folders
x-box-enable-explorer: true
x-box-sanitized: true
x-box-tag: folders
"/folders/{folder_id}#add_shared_link":
put:
description: Adds a shared link to a folder.
operationId: put_folders_id#add_shared_link
parameters:
- description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting this folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folder/123`
the `folder_id` is `123`.
The root folder of a Box account is
always represented by the ID `0`.
example: "12345"
in: path
name: folder_id
required: true
schema:
nullable: false
type: string
- description: |-
Explicitly request the `shared_link` fields
to be returned for this item.
example: shared_link
in: query
name: fields
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
shared_link:
description: |-
The settings for the shared link to create on the folder.
Use an empty object (`{}`) to use the default settings for shared
links.
properties:
access:
description: |-
The level of access for the shared link. This can be
restricted to anyone with the link (`open`), only people
within the company (`company`) and only those who
have been invited to the folder (`collaborators`).
If not set, this field defaults to the access level specified
by the enterprise admin. To create a shared link with this
default setting pass the `shared_link` object with
no `access` field, for example `{ "shared_link": {} }`.
The `company` access level is only available to paid
accounts.
enum:
- open
- company
- collaborators
example: open
type: string
password:
description: |-
The password required to access the shared link. Set the
password to `null` to remove it.
A password can only be set when `access` is set to `open`.
example: do-not-use-this-password
type: string
permissions:
properties:
can_download:
description: |-
If the shared link allows for downloading of files.
This can only be set when `access` is set to
`open` or `company`.
example: true
type: boolean
can_edit:
description: |-
This value can only be `false` for items
with a `type` of `folder`.
example: false
type: boolean
can_preview:
description: |-
If the shared link allows for previewing of files.
This value is always `true`. For shared links on folders
this also applies to any items in the folder.
example: true
type: boolean
type: object
unshared_at:
description: |-
The timestamp at which this shared link will
expire. This field can only be set by
users with paid accounts. The value must be greater than the
current date and time.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
vanity_name:
description: |-
Defines a custom vanity name to use in the shared link URL,
for example `https://app.box.com/v/my-shared-link`.
Custom URLs should not be used when sharing sensitive content
as vanity URLs are a lot easier to guess than regular shared
links.
example: my-shared-link
minLength: 12
type: string
type: object
type: object
responses:
"200":
content:
application/json:
examples:
default:
value:
etag: "1"
id: "12345"
shared_link:
access: open
download_count: 0
download_url: https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf
effective_access: open
effective_permission: can_download
is_password_enabled: false
permissions:
can_download: true
can_edit: false
can_preview: true
preview_count: 0
unshared_at: 2020-09-21T10:34:41-07:00
url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1
vanity_name: null
vanity_url: null
type: folder
schema:
$ref: "#/components/schemas/Folder--Full"
description: |-
Returns the base representation of a folder with a new shared
link attached.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned when there is an incorrect permission combination
"401":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when the access token provided in the `Authorization` header
is not recognized or not provided.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned if the user does not have all the permissions to complete the
update.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned if the folder is not found, or the user does not
have access to the folder.
"405":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned if the `folder_id` is not in a recognized format.
"412":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Add shared link to folder
tags:
- Shared links (Folders)
x-box-enable-explorer: true
x-box-sanitized: true
x-box-tag: shared_links_folders
"/folders/{folder_id}#get_shared_link":
get:
description: Gets the information for a shared link on a folder.
operationId: get_folders_id#get_shared_link
parameters:
- description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting this folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folder/123`
the `folder_id` is `123`.
The root folder of a Box account is
always represented by the ID `0`.
example: "12345"
in: path
name: folder_id
required: true
schema:
nullable: false
type: string
- description: |-
Explicitly request the `shared_link` fields
to be returned for this item.
example: shared_link
in: query
name: fields
required: true
schema:
type: string
responses:
"200":
content:
application/json:
examples:
default:
value:
etag: "1"
id: "12345"
shared_link:
access: open
download_count: 0
download_url: https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf
effective_access: open
effective_permission: can_download
is_password_enabled: false
permissions:
can_download: true
can_edit: false
can_preview: true
preview_count: 0
unshared_at: 2020-09-21T10:34:41-07:00
url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1
vanity_name: null
vanity_url: null
type: folder
schema:
$ref: "#/components/schemas/Folder--Full"
description: |-
Returns the base representation of a folder with the
additional shared link information.
"401":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when the access token provided in the `Authorization` header
is not recognized or not provided.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned if the folder is not found, or the user does not
have access to the folder.
"405":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned if the `folder_id` is not in a recognized format.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get shared link for folder
tags:
- Shared links (Folders)
x-box-enable-explorer: true
x-box-sanitized: true
x-box-tag: shared_links_folders
"/folders/{folder_id}#remove_shared_link":
put:
description: Removes a shared link from a folder.
operationId: put_folders_id#remove_shared_link
parameters:
- description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting this folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folder/123`
the `folder_id` is `123`.
The root folder of a Box account is
always represented by the ID `0`.
example: "12345"
in: path
name: folder_id
required: true
schema:
nullable: false
type: string
- description: |-
Explicitly request the `shared_link` fields
to be returned for this item.
example: shared_link
in: query
name: fields
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
shared_link:
description: |-
By setting this value to `null`, the shared link
is removed from the folder.
example: null
nullable: true
type: object
type: object
responses:
"200":
content:
application/json:
examples:
default:
value:
etag: "1"
id: "12345"
shared_link: null
type: folder
schema:
$ref: "#/components/schemas/Folder--Full"
description: Returns a basic representation of a folder, with the shared link removed.
"401":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when the access token provided in the `Authorization` header
is not recognized or not provided.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned if the user does not have all the permissions to complete the
update.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned if the folder is not found, or the user does not
have access to the folder.
"405":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned if the `folder_id` is not in a recognized format.
"412":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Remove shared link from folder
tags:
- Shared links (Folders)
x-box-enable-explorer: true
x-box-sanitized: true
x-box-tag: shared_links_folders
"/folders/{folder_id}#update_shared_link":
put:
description: Updates a shared link on a folder.
operationId: put_folders_id#update_shared_link
parameters:
- description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting this folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folder/123`
the `folder_id` is `123`.
The root folder of a Box account is
always represented by the ID `0`.
example: "12345"
in: path
name: folder_id
required: true
schema:
nullable: false
type: string
- description: |-
Explicitly request the `shared_link` fields
to be returned for this item.
example: shared_link
in: query
name: fields
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
shared_link:
description: The settings for the shared link to update.
properties:
access:
description: |-
The level of access for the shared link. This can be
restricted to anyone with the link (`open`), only people
within the company (`company`) and only those who
have been invited to the folder (`collaborators`).
If not set, this field defaults to the access level specified
by the enterprise admin. To create a shared link with this
default setting pass the `shared_link` object with
no `access` field, for example `{ "shared_link": {} }`.
The `company` access level is only available to paid
accounts.
enum:
- open
- company
- collaborators
example: open
type: string
password:
description: |-
The password required to access the shared link. Set the
password to `null` to remove it.
A password can only be set when `access` is set to `open`.
example: do-not-use-this-password
type: string
permissions:
properties:
can_download:
description: |-
If the shared link allows for downloading of files.
This can only be set when `access` is set to
`open` or `company`.
example: true
type: boolean
can_edit:
description: |-
This value can only be `false` for items
with a `type` of `folder`.
example: false
type: boolean
can_preview:
description: |-
If the shared link allows for previewing of files.
This value is always `true`. For shared links on folders
this also applies to any items in the folder.
example: true
type: boolean
type: object
unshared_at:
description: |-
The timestamp at which this shared link will
expire. This field can only be set by
users with paid accounts. The value must be greater than the
current date and time.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
vanity_name:
description: |-
Defines a custom vanity name to use in the shared link URL,
for example `https://app.box.com/v/my-shared-link`.
Custom URLs should not be used when sharing sensitive content
as vanity URLs are a lot easier to guess than regular shared
links.
example: my-shared-link
minLength: 12
type: string
type: object
type: object
responses:
"200":
content:
application/json:
examples:
default:
value:
etag: "1"
id: "12345"
shared_link:
access: open
download_count: 0
download_url: https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf
effective_access: open
effective_permission: can_download
is_password_enabled: false
permissions:
can_download: true
can_edit: false
can_preview: true
preview_count: 0
unshared_at: 2020-09-21T10:34:41-07:00
url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1
vanity_name: null
vanity_url: null
type: folder
schema:
$ref: "#/components/schemas/Folder--Full"
description: |-
Returns a basic representation of the folder, with the updated shared
link attached.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned when there is an incorrect permission combination
"401":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when the access token provided in the `Authorization` header
is not recognized or not provided.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned if the user does not have all the permissions to complete the
update.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned if the folder is not found, or the user does not
have access to the folder.
"405":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned if the `folder_id` is not in a recognized format.
"412":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Update shared link on folder
tags:
- Shared links (Folders)
x-box-enable-explorer: true
x-box-sanitized: true
x-box-tag: shared_links_folders
"/folders/{folder_id}/collaborations":
get:
description: |-
Retrieves a list of pending and active collaborations for a
folder. This returns all the users that have access to the folder
or have been invited to the folder.
operationId: get_folders_id_collaborations
parameters:
- description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting this folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folder/123`
the `folder_id` is `123`.
example: "12345"
in: path
name: folder_id
required: true
schema:
nullable: false
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Collaborations"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List folder collaborations
tags:
- Collaborations (List)
x-box-tag: list_collaborations
"/folders/{folder_id}/copy":
post:
description: |-
Creates a copy of a folder within a destination folder.
The original folder will not be changed.
operationId: post_folders_id_copy
parameters:
- description: |-
The unique identifier of the folder to copy.
The ID for any folder can be determined
by visiting this folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folder/123`
the `folder_id` is `123`.
The root folder with the ID `0` can not be copied.
example: "0"
in: path
name: folder_id
required: true
schema:
nullable: false
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
requestBody:
content:
application/json:
schema:
nullable: false
properties:
name:
description: |-
An optional new name for the copied folder.
There are some restrictions to the file name. Names containing
non-printable ASCII characters, forward and backward slashes
(`/`, `\`), as well as names with trailing spaces are
prohibited.
Additionally, the names `.` and `..` are
not allowed either.
example: New Folder
maxLength: 255
minLength: 1
type: string
parent:
description: The destination folder to copy the folder to.
properties:
id:
description: The ID of parent folder
example: "0"
type: string
required:
- id
type: object
required:
- parent
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/Folder--Full"
description: |-
Returns a new folder object representing the copied folder.
Not all available fields are returned by default. Use the
[fields](#param-fields) query parameter to explicitly request
any specific fields.
"304":
description: |-
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":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"500":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error when trying to copy the root folder.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Copy folder
tags:
- Folders
x-box-enable-explorer: true
x-box-tag: folders
"/folders/{folder_id}/items":
get:
description: |-
Retrieves a page of items in a folder. These items can be files,
folders, and web links.
To request more information about the folder itself, like its size,
please use the [Get a folder](#get-folders-id) endpoint instead.
operationId: get_folders_id_items
parameters:
- description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting this folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folder/123`
the `folder_id` is `123`.
The root folder of a Box account is
always represented by the ID `0`.
example: "12345"
in: path
name: folder_id
required: true
schema:
nullable: false
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
Additionally this field can be used to query any metadata
applied to the file by specifying the `metadata` field as well
as the scope and key of the template to retrieve, for example
`?field=metadata.enterprise_12345.contractTemplate`.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
- description: |-
Specifies whether to use marker-based pagination instead of
offset-based pagination. Only one pagination method can
be used at a time.
By setting this value to true, the API will return a `marker` field
that can be passed as a parameter to this endpoint to get the next
page of the response.
example: true
in: query
name: usemarker
required: false
schema:
type: boolean
- description: |-
Defines the position marker at which to begin returning results. This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
in: query
name: marker
required: false
schema:
type: string
- description: |-
The offset of the item at which to begin the response.
Queries with offset parameter value
exceeding 10000 will be rejected
with a 400 response.
example: 1000
in: query
name: offset
required: false
schema:
default: 0
format: int64
type: integer
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
- description: |-
The URL, and optional password, for the shared link of this item.
This header can be used to access items that have not been
explicitly shared with a user.
Use the format `shared_link=[link]` or if a password is required then
use `shared_link=[link]&shared_link_password=[password]`.
This header can be used on the file or folder shared, as well as on any files
or folders nested within the item.
example: shared_link=[link]&shared_link_password=[password]
in: header
name: boxapi
required: false
schema:
type: string
- description: |-
Defines the **second** attribute by which items
are sorted.
Items are always sorted by their `type` first, with
folders listed before files, and files listed
before web links.
This parameter is not supported for marker-based pagination
on the root folder (the folder with an ID of `0`).
example: id
in: query
name: sort
required: false
schema:
enum:
- id
- name
- date
- size
type: string
- description: |-
The direction to sort results in. This can be either in alphabetical ascending
(`ASC`) or descending (`DESC`) order.
example: ASC
in: query
name: direction
required: false
schema:
enum:
- ASC
- DESC
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Items"
description: Returns a collection of files, folders, and web links contained in a folder.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when the access token provided in the `Authorization` header
is not recognized or not provided.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned if the folder is not found, or the user does not
have access to the folder.
"405":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned if the `folder_id` is not in a recognized format.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List items in folder
tags:
- Folders
x-box-enable-explorer: true
x-box-sanitized: true
x-box-tag: folders
"/folders/{folder_id}/metadata":
get:
description: |-
Retrieves all metadata for a given folder. This can not be used on the root
folder with ID `0`.
operationId: get_folders_id_metadata
parameters:
- description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting this folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folder/123`
the `folder_id` is `123`.
The root folder of a Box account is
always represented by the ID `0`.
example: "12345"
in: path
name: folder_id
required: true
schema:
nullable: false
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Metadatas"
description: |-
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.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when the request parameters are not valid.
* `forbidden` - this operation is not allowed on the Root folder.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned when the user does not have access to the folder.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List metadata instances on folder
tags:
- Metadata instances (Folders)
x-box-sanitized: true
x-box-tag: folder_metadata
"/folders/{folder_id}/metadata/enterprise/securityClassification-6VMVochwUWo":
delete:
description: |-
Removes any classifications from a folder.
This API can also be called by including the enterprise ID in the
URL explicitly, for example
`/folders/:id//enterprise_12345/securityClassification-6VMVochwUWo`.
operationId: delete_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo
parameters:
- description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting this folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folder/123`
the `folder_id` is `123`.
The root folder of a Box account is
always represented by the ID `0`.
example: "12345"
in: path
name: folder_id
required: true
schema:
nullable: false
type: string
responses:
"204":
description: |-
Returns an empty response when the classification is
successfully deleted.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned when the request parameters are not valid.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"405":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned when the method was not allowed.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Remove classification from folder
tags:
- Classifications on folders
x-box-sanitized: true
x-box-tag: folder_classifications
get:
description: |-
Retrieves the classification metadata instance that
has been applied to a folder.
This API can also be called by including the enterprise ID in the
URL explicitly, for example
`/folders/:id//enterprise_12345/securityClassification-6VMVochwUWo`.
operationId: get_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo
parameters:
- description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting this folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folder/123`
the `folder_id` is `123`.
The root folder of a Box account is
always represented by the ID `0`.
example: "12345"
in: path
name: folder_id
required: true
schema:
nullable: false
type: string
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/Classification"
description: |-
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.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned when the request parameters are not valid.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"405":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned when the method was not allowed.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get classification on folder
tags:
- Classifications on folders
x-box-sanitized: true
x-box-tag: folder_classifications
post:
description: |-
Adds a classification to a folder by specifying the label of the
classification to add.
This API can also be called by including the enterprise ID in the
URL explicitly, for example
`/folders/:id//enterprise_12345/securityClassification-6VMVochwUWo`.
operationId: post_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo
parameters:
- description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting this folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folder/123`
the `folder_id` is `123`.
The root folder of a Box account is
always represented by the ID `0`.
example: "12345"
in: path
name: folder_id
required: true
schema:
nullable: false
type: string
requestBody:
content:
application/json:
schema:
properties:
Box__Security__Classification__Key:
description: |-
The name of the classification to apply to this folder.
To list the available classifications in an enterprise,
use the classification API to retrieve the
[classification template](e://get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema)
which lists all available classification keys.
example: Sensitive
type: string
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/Classification"
description: |-
Returns the classification template instance
that was applied to the folder.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error when the request body is not valid.
* `schema_validation_failed` - The request body contains a value for a 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.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Add classification to folder
tags:
- Classifications on folders
x-box-sanitized: true
x-box-tag: folder_classifications
put:
description: |-
Updates a classification on a folder.
The classification can only be updated if a classification has already been
applied to the folder before. When editing classifications, only values are
defined for the enterprise will be accepted.
operationId: put_folders_id_metadata_enterprise_securityClassification-6VMVochwUWo
parameters:
- description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting this folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folder/123`
the `folder_id` is `123`.
The root folder of a Box account is
always represented by the ID `0`.
example: "12345"
in: path
name: folder_id
required: true
schema:
nullable: false
type: string
requestBody:
content:
application/json-patch+json:
schema:
description: |-
A list containing the one change to make, to
update the classification label.
items:
description: |-
The operation to perform on the classification
metadata template instance. In this case, it use
used to replace the value stored for the
`Box__Security__Classification__Key` field with a new
value.
properties:
op:
description: "`replace`"
enum:
- replace
example: replace
type: string
path:
description: "`/Box__Security__Classification__Key`"
enum:
- /Box__Security__Classification__Key
example: /Box__Security__Classification__Key
type: string
value:
description: |-
The name of the classification to apply to this folder.
To list the available classifications in an enterprise,
use the classification API to retrieve the
[classification template](e://get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema)
which lists all available classification keys.
example: Sensitive
type: string
type: object
type: array
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Classification"
description: Returns the updated classification metadata template instance.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"500":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error in some edge cases when the request body is not a valid
array of JSON Patch items.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Update classification on folder
tags:
- Classifications on folders
x-box-sanitized: true
x-box-tag: folder_classifications
"/folders/{folder_id}/metadata/{scope}/{template_key}":
delete:
description: Deletes a piece of folder metadata.
operationId: delete_folders_id_metadata_id_id
parameters:
- description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting this folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folder/123`
the `folder_id` is `123`.
The root folder of a Box account is
always represented by the ID `0`.
example: "12345"
in: path
name: folder_id
required: true
schema:
nullable: false
type: string
- description: The scope of the metadata template
example: global
in: path
name: scope
required: true
schema:
enum:
- global
- enterprise
type: string
- description: The name of the metadata template
example: properties
in: path
name: template_key
required: true
schema:
type: string
responses:
"204":
description: |-
Returns an empty response when the metadata is
successfully deleted.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when the request parameters are not valid. This may happen of the
`scope` is not valid.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"405":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when the method was not allowed. This often happens when the
folder ID is not valid or the root folder with ID `0`.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Remove metadata instance from folder
tags:
- Metadata instances (Folders)
x-box-sanitized: true
x-box-tag: folder_metadata
get:
description: |-
Retrieves the instance of a metadata template that has been applied to a
folder. This can not be used on the root folder with ID `0`.
operationId: get_folders_id_metadata_id_id
parameters:
- description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting this folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folder/123`
the `folder_id` is `123`.
The root folder of a Box account is
always represented by the ID `0`.
example: "12345"
in: path
name: folder_id
required: true
schema:
nullable: false
type: string
- description: The scope of the metadata template
example: global
in: path
name: scope
required: true
schema:
enum:
- global
- enterprise
type: string
- description: The name of the metadata template
example: properties
in: path
name: template_key
required: true
schema:
type: string
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/Metadata"
description: |-
An instance of the metadata template that includes
additional "key:value" pairs defined by the user or
an application.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned when the request parameters are not valid.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"405":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when the method was not allowed. This often happens when the
folder ID is not valid or the root folder with ID `0`.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get metadata instance on folder
tags:
- Metadata instances (Folders)
x-box-sanitized: true
x-box-tag: folder_metadata
post:
description: |-
Applies an instance of a metadata template to a folder.
In most cases only values that are present in the metadata template
will be accepted, except for the `global.properties` template which accepts
any key-value pair.
To display the metadata template in the Box web app the enterprise needs to be
configured to enable **Cascading Folder Level Metadata** for the user in the
admin console.
operationId: post_folders_id_metadata_id_id
parameters:
- description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting this folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folder/123`
the `folder_id` is `123`.
The root folder of a Box account is
always represented by the ID `0`.
example: "12345"
in: path
name: folder_id
required: true
schema:
nullable: false
type: string
- description: The scope of the metadata template
example: global
in: path
name: scope
required: true
schema:
enum:
- global
- enterprise
type: string
- description: The name of the metadata template
example: properties
in: path
name: template_key
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
additionalProperties:
description: |-
A value for each of the fields that are present on the metadata
template.
For the `global.properties` template this can be an a list of zero
or more fields, as this template allows for any generic key-value
pairs to be stored on the template.
example: Aaron Levie
type: string
x-box-example-key: name
example:
name: Aaron Levie
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/Metadata"
description: |-
Returns the instance of the template that was applied to the folder,
including the data that was applied to the template.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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 file.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Create metadata instance on folder
tags:
- Metadata instances (Folders)
x-box-enable-explorer: false
x-box-sanitized: true
x-box-tag: folder_metadata
put:
description: |-
Updates a piece of metadata on a folder.
The metadata instance can only be updated if the template has already been
applied to the folder before. When editing metadata, only values that match
the metadata template schema will be accepted.
The update is applied atomically. If any errors occur during the
application of the operations, the metadata instance will not be changed.
operationId: put_folders_id_metadata_id_id
parameters:
- description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting this folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folder/123`
the `folder_id` is `123`.
The root folder of a Box account is
always represented by the ID `0`.
example: "12345"
in: path
name: folder_id
required: true
schema:
nullable: false
type: string
- description: The scope of the metadata template
example: global
in: path
name: scope
required: true
schema:
enum:
- global
- enterprise
type: string
- description: The name of the metadata template
example: properties
in: path
name: template_key
required: true
schema:
type: string
requestBody:
content:
application/json-patch+json:
schema:
description: |-
A [JSON-Patch](https://tools.ietf.org/html/rfc6902)
specification for the changes to make to the metadata
instance.
The changes are represented as a JSON array of
operation objects.
items:
description: |-
A [JSON-Patch](https://tools.ietf.org/html/rfc6902) operation for a
change to make to the metadata instance.
properties:
from:
description: |-
The location in the metadata JSON object to move or copy a value
from. Required for `move` or `copy` operations and must be in the
format of a [JSON-Pointer](https://tools.ietf.org/html/rfc6901).
example: /nextState
type: string
op:
description: |-
The type of change to perform on the template. Some
of these are hazardous as they will change existing templates.
enum:
- add
- replace
- remove
- test
- move
- copy
example: add
type: string
path:
description: |-
The location in the metadata JSON object
to apply the changes to, in the format of a
[JSON-Pointer](https://tools.ietf.org/html/rfc6901).
The path must always be prefixed with a `/` to represent the root
of the template. The characters `~` and `/` are reserved
characters and must be escaped in the key.
example: /currentState
type: string
value:
description: |-
The value to be set or tested.
Required for `add`, `replace`, and `test` operations. For `add`,
if the value exists already the previous value will be overwritten
by the new value. For `replace`, the value must exist before
replacing.
For `test`, the existing value at the `path` location must match
the specified value.
example: reviewed
type: string
title: A metadata instance update operation
type: object
type: array
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Metadata"
description: |-
Returns the updated metadata template instance, with the
custom template data included.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"500":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error in some edge cases when the request body is not a valid
array of JSON Patch items.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Update metadata instance on folder
tags:
- Metadata instances (Folders)
x-box-sanitized: true
x-box-tag: folder_metadata
"/folders/{folder_id}/trash":
delete:
description: |-
Permanently deletes a folder that is in the trash.
This action cannot be undone.
operationId: delete_folders_id_trash
parameters:
- description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting this folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folder/123`
the `folder_id` is `123`.
The root folder of a Box account is
always represented by the ID `0`.
example: "12345"
in: path
name: folder_id
required: true
schema:
nullable: false
type: string
responses:
"204":
description: |-
Returns an empty response when the folder was
permanently deleted.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if the folder is not in the trash.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Permanently remove folder
tags:
- Trashed folders
x-box-tag: trashed_folders
get:
description: |-
Retrieves a folder that has been moved to the trash.
Please note that only if the folder itself has been moved to the
trash can it be retrieved with this API call. If instead one of
its parent folders was moved to the trash, only that folder
can be inspected using the
[`GET /folders/:id/trash`](e://get_folders_id_trash) API.
To list all items that have been moved to the trash, please
use the [`GET /folders/trash/items`](e://get-folders-trash-items/)
API.
operationId: get_folders_id_trash
parameters:
- description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting this folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folder/123`
the `folder_id` is `123`.
The root folder of a Box account is
always represented by the ID `0`.
example: "12345"
in: path
name: folder_id
required: true
schema:
nullable: false
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/TrashFolder"
description: |-
Returns the folder that was trashed,
including information about when the it
was moved to the trash.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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`](e://get_folders_id_trash) API.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get trashed folder
tags:
- Trashed folders
x-box-tag: trashed_folders
"/folders/{folder_id}/watermark":
delete:
description: Removes the watermark from a folder.
operationId: delete_folders_id_watermark
parameters:
- description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting this folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folder/123`
the `folder_id` is `123`.
The root folder of a Box account is
always represented by the ID `0`.
example: "12345"
in: path
name: folder_id
required: true
schema:
nullable: false
type: string
responses:
"204":
description: |-
An empty response will be returned when the watermark
was successfully deleted.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if the folder did not have
a watermark applied to it
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Remove watermark from folder
tags:
- Watermarks (Folders)
x-box-tag: folder_watermarks
get:
description: Retrieve the watermark for a folder.
operationId: get_folders_id_watermark
parameters:
- description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting this folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folder/123`
the `folder_id` is `123`.
The root folder of a Box account is
always represented by the ID `0`.
example: "12345"
in: path
name: folder_id
required: true
schema:
nullable: false
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Watermark"
description: |-
Returns an object containing information about the
watermark associated for to this folder.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if the folder does not have a watermark applied.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get watermark for folder
tags:
- Watermarks (Folders)
x-box-tag: folder_watermarks
put:
description: Applies or update a watermark on a folder.
operationId: put_folders_id_watermark
parameters:
- description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting this folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folder/123`
the `folder_id` is `123`.
The root folder of a Box account is
always represented by the ID `0`.
example: "12345"
in: path
name: folder_id
required: true
schema:
nullable: false
type: string
requestBody:
content:
application/json:
schema:
properties:
watermark:
description: The watermark to imprint on the folder
properties:
imprint:
description: |-
The type of watermark to apply.
Currently only supports one option.
enum:
- default
example: default
type: string
required:
- imprint
type: object
required:
- watermark
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Watermark"
description: |-
Returns an updated watermark if a watermark already
existed on this folder.
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/Watermark"
description: |-
Returns a new watermark if no watermark existed on
this folder yet.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Apply watermark to folder
tags:
- Watermarks (Folders)
x-box-tag: folder_watermarks
/group_memberships:
post:
description: |-
Creates a group membership. Only users with
admin-level permissions will be able to use this API.
operationId: post_group_memberships
parameters:
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
requestBody:
content:
application/json:
schema:
properties:
configurable_permissions:
additionalProperties:
description: A key value pair of custom permissions.
example: true
type: boolean
x-box-example-key: can_run_reports
description: |-
Custom configuration for the permissions an admin
if a group will receive. This option has no effect
on members with a role of `member`.
Setting these permissions overwrites the default
access levels of an admin.
Specifying a value of "null" for this object will disable
all configurable permissions. Specifying permissions will set
them accordingly, omitted permissions will be enabled by default.
example:
can_run_reports: true
type: object
group:
description: The group to add the user to.
properties:
id:
description: The ID of the group to add the user to
example: "4545523"
type: string
required:
- id
type: object
role:
description: The role of the user in the group.
enum:
- member
- admin
example: member
type: string
user:
description: The user to add to the group.
properties:
id:
description: The ID of the user to add to the group
example: "1434325"
type: string
required:
- id
type: object
required:
- user
- group
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/GroupMembership"
description: Returns a new group membership object.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Add user to group
tags:
- Group memberships
x-box-tag: memberships
"/group_memberships/{group_membership_id}":
delete:
description: |-
Deletes a specific group membership. Only admins of this
group or users with admin-level permissions will be able to
use this API.
operationId: delete_group_memberships_id
parameters:
- description: The ID of the group membership.
example: "434534"
in: path
name: group_membership_id
required: true
schema:
type: string
responses:
"204":
description: |-
A blank response is returned if the membership was
successfully deleted.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Remove user from group
tags:
- Group memberships
x-box-tag: memberships
get:
description: |-
Retrieves a specific group membership. Only admins of this
group or users with admin-level permissions will be able to
use this API.
operationId: get_group_memberships_id
parameters:
- description: The ID of the group membership.
example: "434534"
in: path
name: group_membership_id
required: true
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/GroupMembership"
description: Returns the group membership object.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get group membership
tags:
- Group memberships
x-box-tag: memberships
put:
description: |-
Updates a user's group membership. Only admins of this
group or users with admin-level permissions will be able to
use this API.
operationId: put_group_memberships_id
parameters:
- description: The ID of the group membership.
example: "434534"
in: path
name: group_membership_id
required: true
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
requestBody:
content:
application/json:
schema:
properties:
configurable_permissions:
additionalProperties:
description: A key value pair of custom permissions.
example: true
type: boolean
x-box-example-key: can_run_reports
description: |-
Custom configuration for the permissions an admin
if a group will receive. This option has no effect
on members with a role of `member`.
Setting these permissions overwrites the default
access levels of an admin.
Specifying a value of "null" for this object will disable
all configurable permissions. Specifying permissions will set
them accordingly, omitted permissions will be enabled by default.
example:
can_run_reports: true
type: object
role:
description: The role of the user in the group.
enum:
- member
- admin
example: member
type: string
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/GroupMembership"
description: Returns a new group membership object.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Update group membership
tags:
- Group memberships
x-box-tag: memberships
/groups:
get:
description: |-
Retrieves all of the groups for a given enterprise. The user
must have admin permissions to inspect enterprise's groups.
operationId: get_groups
parameters:
- description: |-
Limits the results to only groups whose `name` starts
with the search term.
example: Engineering
in: query
name: filter_term
required: false
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
- description: |-
The offset of the item at which to begin the response.
Queries with offset parameter value
exceeding 10000 will be rejected
with a 400 response.
example: 1000
in: query
name: offset
required: false
schema:
default: 0
format: int64
type: integer
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Groups"
description: |-
Returns a collection of group objects. If there are no groups, an
empty collection will be returned.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List groups for enterprise
tags:
- Groups
x-box-tag: groups
post:
description: |-
Creates a new group of users in an enterprise. Only users with admin
permissions can create new groups.
operationId: post_groups
parameters:
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
requestBody:
content:
application/json:
schema:
properties:
description:
description: A human readable description of the group.
example: '"Customer Support Group - as imported from Active Directory"'
maxLength: 255
type: string
external_sync_identifier:
description: |-
An arbitrary identifier that can be used by
external group sync tools to link this Box Group to
an external group.
Example values of this field
could be an **Active Directory Object ID** or a **Google
Group ID**.
We recommend you use of this field in
order to avoid issues when group names are updated in
either Box or external systems.
example: AD:123456
type: string
invitability_level:
description: |-
Specifies who can invite the group to collaborate
on folders.
When set to `admins_only` the enterprise admin, co-admins,
and the group's admin can invite the group.
When set to `admins_and_members` all the admins listed
above and group members can invite the group.
When set to `all_managed_users` all managed users in the
enterprise can invite the group.
enum:
- admins_only
- admins_and_members
- all_managed_users
example: admins_only
type: string
member_viewability_level:
description: |-
Specifies who can see the members of the group.
* `admins_only` - the enterprise admin, co-admins, group's
group admin
* `admins_and_members` - all admins and group members
* `all_managed_users` - all managed users in the
enterprise
enum:
- admins_only
- admins_and_members
- all_managed_users
example: admins_only
type: string
name:
description: |-
The name of the new group to be created. This name must be unique
within the enterprise.
example: Customer Support
type: string
provenance:
description: |-
Keeps track of which external source this group is
coming, for example `Active Directory`, or `Okta`.
Setting this will also prevent Box admins from editing
the group name and its members directly via the Box
web application.
This is desirable for one-way syncing of groups.
example: Active Directory
maxLength: 255
type: string
required:
- name
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/Group"
description: Returns the new group object.
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Create group
tags:
- Groups
x-box-tag: groups
/groups/terminate_sessions:
post:
description: |-
Validates the roles and permissions of the group,
and creates asynchronous jobs
to terminate the group's sessions.
Returns the status for the POST request.
operationId: post_groups_terminate_sessions
requestBody:
content:
application/json:
schema:
properties:
group_ids:
description: A list of group IDs
example:
- "123456"
- "456789"
items:
type: string
type: array
required:
- group_ids
type: object
responses:
"202":
content:
application/json:
schema:
$ref: "#/components/schemas/SessionTerminationMessage"
description: Returns a message about the request status.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if there are insufficient permissions.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if the resource could not be found.
"429":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if the request limit is exceeded.
"500":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if there is an internal server issue.
"503":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if the request timed out.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Create jobs to terminate user group session
tags:
- Groups
x-box-tag: session_termination
"/groups/{group_id}":
delete:
description: |-
Permanently deletes a group. Only users with
admin-level permissions will be able to use this API.
operationId: delete_groups_id
parameters:
- description: The ID of the group.
example: "57645"
in: path
name: group_id
required: true
schema:
type: string
responses:
"204":
description: |-
A blank response is returned if the group was
successfully deleted.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Remove group
tags:
- Groups
x-box-tag: groups
get:
description: |-
Retrieves information about a group. Only members of this
group or users with admin-level permissions will be able to
use this API.
operationId: get_groups_id
parameters:
- description: The ID of the group.
example: "57645"
in: path
name: group_id
required: true
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Group--Full"
description: Returns the group object
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get group
tags:
- Groups
x-box-tag: groups
put:
description: |-
Updates a specific group. Only admins of this
group or users with admin-level permissions will be able to
use this API.
operationId: put_groups_id
parameters:
- description: The ID of the group.
example: "57645"
in: path
name: group_id
required: true
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
requestBody:
content:
application/json:
schema:
properties:
description:
description: A human readable description of the group.
example: '"Customer Support Group - as imported from Active Directory"'
maxLength: 255
type: string
external_sync_identifier:
description: |-
An arbitrary identifier that can be used by
external group sync tools to link this Box Group to
an external group.
Example values of this field
could be an **Active Directory Object ID** or a **Google
Group ID**.
We recommend you use of this field in
order to avoid issues when group names are updated in
either Box or external systems.
example: AD:123456
type: string
invitability_level:
description: |-
Specifies who can invite the group to collaborate
on folders.
When set to `admins_only` the enterprise admin, co-admins,
and the group's admin can invite the group.
When set to `admins_and_members` all the admins listed
above and group members can invite the group.
When set to `all_managed_users` all managed users in the
enterprise can invite the group.
enum:
- admins_only
- admins_and_members
- all_managed_users
example: admins_only
type: string
member_viewability_level:
description: |-
Specifies who can see the members of the group.
* `admins_only` - the enterprise admin, co-admins, group's
group admin
* `admins_and_members` - all admins and group members
* `all_managed_users` - all managed users in the
enterprise
enum:
- admins_only
- admins_and_members
- all_managed_users
example: admins_only
type: string
name:
description: |-
The name of the new group to be created. Must be unique within the
enterprise.
example: Customer Support
type: string
provenance:
description: |-
Keeps track of which external source this group is
coming, for example `Active Directory`, or `Okta`.
Setting this will also prevent Box admins from editing
the group name and its members directly via the Box
web application.
This is desirable for one-way syncing of groups.
example: Active Directory
maxLength: 255
type: string
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Group--Full"
description: Returns the updated group object.
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Update group
tags:
- Groups
x-box-tag: groups
"/groups/{group_id}/collaborations":
get:
description: |-
Retrieves all the collaborations for a group. The user
must have admin permissions to inspect enterprise's groups.
Each collaboration object has details on which files or
folders the group has access to and with what role.
operationId: get_groups_id_collaborations
parameters:
- description: The ID of the group.
example: "57645"
in: path
name: group_id
required: true
schema:
type: string
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
- description: |-
The offset of the item at which to begin the response.
Queries with offset parameter value
exceeding 10000 will be rejected
with a 400 response.
example: 1000
in: query
name: offset
required: false
schema:
default: 0
format: int64
type: integer
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Collaborations"
description: |-
Returns a collection of collaboration objects. If there are no
collaborations, an empty collection will be returned.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List group collaborations
tags:
- Collaborations (List)
x-box-tag: list_collaborations
"/groups/{group_id}/memberships":
get:
description: |-
Retrieves all the members for a group. Only members of this
group or users with admin-level permissions will be able to
use this API.
operationId: get_groups_id_memberships
parameters:
- description: The ID of the group.
example: "57645"
in: path
name: group_id
required: true
schema:
type: string
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
- description: |-
The offset of the item at which to begin the response.
Queries with offset parameter value
exceeding 10000 will be rejected
with a 400 response.
example: 1000
in: query
name: offset
required: false
schema:
default: 0
format: int64
type: integer
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/GroupMemberships"
description: |-
Returns a collection of membership objects. If there are no
memberships, an empty collection will be returned.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List members of group
tags:
- Group memberships
x-box-tag: memberships
/invites:
post:
description: |-
Invites an existing external user to join an enterprise.
The existing user can not be part of another enterprise and
must already have a Box account. Once invited, the user will receive an
email and are prompted to accept the invitation within the
Box web application.
This method requires the "Manage An Enterprise" scope enabled for
the application, which can be enabled within the developer console.
operationId: post_invites
parameters:
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
requestBody:
content:
application/json:
schema:
properties:
actionable_by:
description: The user to invite
properties:
login:
description: The login of the invited user
example: john@example.com
type: string
required:
- id
type: object
enterprise:
description: The enterprise to invite the user to
properties:
id:
description: The ID of the enterprise
example: "1232234"
type: string
required:
- id
type: object
required:
- enterprise
- actionable_by
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Invite"
description: Returns a new invite object.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Create user invite
tags:
- Invites
x-box-tag: invites
"/invites/{invite_id}":
get:
description: Returns the status of a user invite.
operationId: get_invites_id
parameters:
- description: The ID of an invite.
example: "213723"
in: path
name: invite_id
required: true
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Invite"
description: Returns an invite object
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get user invite status
tags:
- Invites
x-box-tag: invites
/legal_hold_policies:
get:
description: |-
Retrieves a list of legal hold policies that belong to
an enterprise.
operationId: get_legal_hold_policies
parameters:
- description: |-
Limits results to policies for which the names start with
this search term. This is a case-insensitive prefix.
example: Sales Policy
in: query
name: policy_name
required: false
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
- description: |-
Defines the position marker at which to begin returning results. This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
in: query
name: marker
required: false
schema:
type: string
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/LegalHoldPolicies"
description: Returns a list of legal hold policies.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List all legal hold policies
tags:
- Legal hold policies
x-box-tag: legal_hold_policies
post:
description: Create a new legal hold policy.
operationId: post_legal_hold_policies
requestBody:
content:
application/json:
schema:
properties:
description:
description: A description for the policy.
example: A custom policy for the sales team
maxLength: 500
type: string
filter_ended_at:
description: |-
The filter end date.
When this policy is applied using a `custodian` legal
hold assignments, it will only apply to file versions
created or uploaded inside of the
date range. Other assignment types, such as folders and
files, will ignore the date filter.
Required if `is_ongoing` is set to `false`.
example: 2012-12-18T10:53:43-08:00
format: date-time
maxLength: 500
type: string
filter_started_at:
description: |-
The filter start date.
When this policy is applied using a `custodian` legal
hold assignments, it will only apply to file versions
created or uploaded inside of the
date range. Other assignment types, such as folders and
files, will ignore the date filter.
Required if `is_ongoing` is set to `false`.
example: 2012-12-12T10:53:43-08:00
format: date-time
maxLength: 500
type: string
is_ongoing:
description: |-
Whether new assignments under this policy should
continue applying to files even after initialization.
When this policy is applied using a legal hold assignment,
it will continue applying the policy to any new file versions
even after it has been applied.
For example, if a legal hold assignment is placed on a user
today, and that user uploads a file tomorrow, that file will
get held. This will continue until the policy is retired.
Required if no filter dates are set.
example: true
type: boolean
policy_name:
description: The name of the policy.
example: Sales Policy
maxLength: 254
type: string
required:
- policy_name
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/LegalHoldPolicy"
description: Returns a new legal hold policy object.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if required parameters are missing,
or neither `is_ongoing` or filter dates are specified.
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if a policy with this name already exists.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Create legal hold policy
tags:
- Legal hold policies
x-box-tag: legal_hold_policies
"/legal_hold_policies/{legal_hold_policy_id}":
delete:
description: |-
Delete an existing legal hold policy.
This is an asynchronous process. The policy will not be
fully deleted yet when the response returns.
operationId: delete_legal_hold_policies_id
parameters:
- description: The ID of the legal hold policy
example: "324432"
in: path
name: legal_hold_policy_id
required: true
schema:
type: string
responses:
"202":
description: |-
A blank response is returned if the policy was
successfully deleted.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Remove legal hold policy
tags:
- Legal hold policies
x-box-tag: legal_hold_policies
get:
description: Retrieve a legal hold policy.
operationId: get_legal_hold_policies_id
parameters:
- description: The ID of the legal hold policy
example: "324432"
in: path
name: legal_hold_policy_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/LegalHoldPolicy"
description: Returns a legal hold policy object.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get legal hold policy
tags:
- Legal hold policies
x-box-tag: legal_hold_policies
put:
description: Update legal hold policy.
operationId: put_legal_hold_policies_id
parameters:
- description: The ID of the legal hold policy
example: "324432"
in: path
name: legal_hold_policy_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
description:
description: A description for the policy.
example: A custom policy for the sales team
maxLength: 500
type: string
policy_name:
description: The name of the policy.
example: Sales Policy
maxLength: 254
type: string
release_notes:
description: Notes around why the policy was released.
example: Required for GDPR
maxLength: 500
type: string
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/LegalHoldPolicy"
description: Returns a new legal hold policy object.
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if a policy with this name already exists.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Update legal hold policy
tags:
- Legal hold policies
x-box-tag: legal_hold_policies
/legal_hold_policy_assignments:
get:
description: Retrieves a list of items a legal hold policy has been assigned to.
operationId: get_legal_hold_policy_assignments
parameters:
- description: The ID of the legal hold policy
example: "324432"
in: query
name: policy_id
required: true
schema:
type: string
- description: |-
Filters the results by the type of item the
policy was applied to.
example: file
in: query
name: assign_to_type
schema:
enum:
- file
- file_version
- folder
- user
type: string
- description: |-
Filters the results by the ID of item the
policy was applied to.
example: "1234323"
in: query
name: assign_to_id
schema:
type: string
- description: |-
Defines the position marker at which to begin returning results. This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
in: query
name: marker
required: false
schema:
type: string
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/LegalHoldPolicyAssignments"
description: Returns a list of legal hold policy assignments.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List legal hold policy assignments
tags:
- Legal hold policy assignments
x-box-tag: legal_hold_policy_assignments
post:
description: Assign a legal hold to a file, file version, folder, or user.
operationId: post_legal_hold_policy_assignments
requestBody:
content:
application/json:
schema:
properties:
assign_to:
description: The item to assign the policy to
properties:
id:
description: The ID of item to assign the policy to
example: "6564564"
type: string
type:
description: The type of item to assign the policy to
enum:
- file
- file_version
- folder
- user
example: folder
type: string
required:
- type
- id
type: object
policy_id:
description: The ID of the policy to assign.
example: "123244"
type: string
required:
- policy_id
- assign_to
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/LegalHoldPolicyAssignment"
description: Returns a new legal hold policy assignment.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Assign legal hold policy
tags:
- Legal hold policy assignments
x-box-tag: legal_hold_policy_assignments
"/legal_hold_policy_assignments/{legal_hold_policy_assignment_id}":
delete:
description: |-
Remove a legal hold from an item.
This is an asynchronous process. The policy will not be
fully removed yet when the response returns.
operationId: delete_legal_hold_policy_assignments_id
parameters:
- description: The ID of the legal hold policy assignment
example: "753465"
in: path
name: legal_hold_policy_assignment_id
required: true
schema:
type: string
responses:
"202":
description: |-
A blank response is returned if the assignment was
successfully deleted.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Unassign legal hold policy
tags:
- Legal hold policy assignments
x-box-tag: legal_hold_policy_assignments
get:
description: Retrieve a legal hold policy assignment.
operationId: get_legal_hold_policy_assignments_id
parameters:
- description: The ID of the legal hold policy assignment
example: "753465"
in: path
name: legal_hold_policy_assignment_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/LegalHoldPolicyAssignment"
description: Returns a legal hold policy object.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get legal hold policy assignment
tags:
- Legal hold policy assignments
x-box-tag: legal_hold_policy_assignments
"/legal_hold_policy_assignments/{legal_hold_policy_assignment_id}/file_versions_on_hold":
get:
description: |-
Get a list of previous file versions for a legal hold
assignment.
In some cases you may only need the latest file versions instead. In these
cases, use the `GET /legal_hold_policy_assignments/:id/files_on_hold` API
instead to return any current (latest) versions of a file for this legal hold
policy assignment.
Due to ongoing re-architecture efforts this API might not return all files
held for this policy ID. Instead, this API will only return past file versions
held in the newly developed architecture. The `GET /file_version_legal_holds`
API can be used to fetch current and past versions of files held within the
legacy architecture.
The `GET /legal_hold_policy_assignments?policy_id={id}` API can be used to
find a list of policy assignments for a given policy ID.
operationId: get_legal_hold_policy_assignments_id_file_versions_on_hold
parameters:
- description: The ID of the legal hold policy assignment
example: "753465"
in: path
name: legal_hold_policy_assignment_id
required: true
schema:
type: string
- description: |-
Defines the position marker at which to begin returning results. This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
in: query
name: marker
required: false
schema:
type: string
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/FileVersionLegalHolds"
description: |-
Returns the list of previous file versions held under legal hold for a
specific legal hold policy assignment.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List previous file versions for legal hold policy assignment
tags:
- Legal hold policy assignments
x-box-tag: legal_hold_policy_assignments
"/legal_hold_policy_assignments/{legal_hold_policy_assignment_id}/files_on_hold":
get:
description: |-
Get a list of current file versions for a legal hold
assignment.
In some cases you may want to get previous file versions instead. In these
cases, use the `GET /legal_hold_policy_assignments/:id/file_versions_on_hold`
API instead to return any previous versions of a file for this legal hold
policy assignment.
Due to ongoing re-architecture efforts this API might not return all file
versions held for this policy ID. Instead, this API will only return the
latest file version held in the newly developed architecture. The `GET
/file_version_legal_holds` API can be used to fetch current and past versions
of files held within the legacy architecture.
The `GET /legal_hold_policy_assignments?policy_id={id}` API can be used to
find a list of policy assignments for a given policy ID.
operationId: get_legal_hold_policy_assignments_id_files_on_hold
parameters:
- description: The ID of the legal hold policy assignment
example: "753465"
in: path
name: legal_hold_policy_assignment_id
required: true
schema:
type: string
- description: |-
Defines the position marker at which to begin returning results. This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
in: query
name: marker
required: false
schema:
type: string
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/FileVersionLegalHolds"
description: |-
Returns the list of current file versions held under legal hold for a
specific legal hold policy assignment.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List current file versions for legal hold policy assignment
tags:
- Legal hold policy assignments
x-box-tag: legal_hold_policy_assignments
/metadata_cascade_policies:
get:
description: |-
Retrieves a list of all the metadata cascade policies
that are applied to a given folder. This can not be used on the root
folder with ID `0`.
operationId: get_metadata_cascade_policies
parameters:
- description: |-
Specifies which folder to return policies for. This can not be used on the
root folder with ID `0`.
example: "31232"
in: query
name: folder_id
required: true
schema:
type: string
- description: |-
The ID of the enterprise ID for which to find metadata
cascade policies. If not specified, it defaults to the
current enterprise.
example: "31232"
in: query
name: owner_enterprise_id
schema:
type: string
- description: |-
Defines the position marker at which to begin returning results. This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
in: query
name: marker
required: false
schema:
type: string
- description: |-
The offset of the item at which to begin the response.
Queries with offset parameter value
exceeding 10000 will be rejected
with a 400 response.
example: 1000
in: query
name: offset
required: false
schema:
default: 0
format: int64
type: integer
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/MetadataCascadePolicies"
description: Returns a list of metadata cascade policies
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error when any of the parameters are not in a valid format.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error when the folder can not be accessed. This error often
happens when accessing the root folder with ID `0`.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List metadata cascade policies
tags:
- Metadata cascade policies
x-box-sanitized: true
x-box-tag: metadata_cascade_policies
post:
description: |-
Creates a new metadata cascade policy that applies a given
metadata template to a given folder and automatically
cascades it down to any files within that folder.
In order for the policy to be applied a metadata instance must first
be applied to the folder the policy is to be applied to.
operationId: post_metadata_cascade_policies
requestBody:
content:
application/json:
schema:
properties:
folder_id:
description: |-
The ID of the folder to apply the policy to. This folder will
need to already have an instance of the targeted metadata
template applied to it.
example: "1234567"
type: string
scope:
description: |-
The scope of the targeted metadata template. This template will
need to already have an instance applied to the targeted folder.
enum:
- global
- enterprise
example: enterprise
type: string
templateKey:
description: |-
The key of the targeted metadata template. This template will
need to already have an instance applied to the targeted folder.
In many cases the template key is automatically derived
of its display name, for example `Contract Template` would
become `contractTemplate`. In some cases the creator of the
template will have provided its own template key.
Please [list the templates for an enterprise][list], or
get all instances on a [file][file] or [folder][folder]
to inspect a template's key.
[list]: e://get-metadata-templates-enterprise
[file]: e://get-files-id-metadata
[folder]: e://get-folders-id-metadata
example: productInfo
type: string
required:
- folder_id
- scope
- templateKey
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/MetadataCascadePolicy"
description: Returns a new of metadata cascade policy
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ConflictError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Create metadata cascade policy
tags:
- Metadata cascade policies
x-box-sanitized: true
x-box-tag: metadata_cascade_policies
"/metadata_cascade_policies/{metadata_cascade_policy_id}":
delete:
description: Deletes a metadata cascade policy.
operationId: delete_metadata_cascade_policies_id
parameters:
- description: The ID of the metadata cascade policy.
example: 6fd4ff89-8fc1-42cf-8b29-1890dedd26d7
in: path
name: metadata_cascade_policy_id
required: true
schema:
type: string
responses:
"204":
description: |-
Returns an empty response when the policy
is successfully deleted.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Remove metadata cascade policy
tags:
- Metadata cascade policies
x-box-sanitized: true
x-box-tag: metadata_cascade_policies
get:
description: Retrieve a specific metadata cascade policy assigned to a folder.
operationId: get_metadata_cascade_policies_id
parameters:
- description: The ID of the metadata cascade policy.
example: 6fd4ff89-8fc1-42cf-8b29-1890dedd26d7
in: path
name: metadata_cascade_policy_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/MetadataCascadePolicy"
description: Returns a metadata cascade policy
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get metadata cascade policy
tags:
- Metadata cascade policies
x-box-sanitized: true
x-box-tag: metadata_cascade_policies
"/metadata_cascade_policies/{metadata_cascade_policy_id}/apply":
post:
description: |-
Force the metadata on a folder with a metadata cascade policy to be applied to
all of its children. This can be used after creating a new cascade policy to
enforce the metadata to be cascaded down to all existing files within that
folder.
operationId: post_metadata_cascade_policies_id_apply
parameters:
- description: The ID of the cascade policy to force-apply.
example: 6fd4ff89-8fc1-42cf-8b29-1890dedd26d7
in: path
name: metadata_cascade_policy_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
conflict_resolution:
description: |-
Describes the desired behavior when dealing with the conflict
where a metadata template already has an instance applied
to a child.
* `none` will preserve the existing value on the file
* `overwrite` will force-apply the templates values over
any existing values.
enum:
- none
- overwrite
example: none
type: string
required:
- conflict_resolution
type: object
responses:
"202":
description: |-
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":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Force-apply metadata cascade policy to folder
tags:
- Metadata cascade policies
x-box-sanitized: true
x-box-tag: metadata_cascade_policies
/metadata_queries/execute_read:
post:
description: |-
Create a search using SQL-like syntax to return items that match specific
metadata.
By default, this endpoint returns only the most basic info about the items for
which the query matches. To get additional fields for each item, including any
of the metadata, use the `fields` attribute in the query.
operationId: post_metadata_queries_execute_read
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/MetadataQuery"
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/MetadataQueryResults"
description: Returns a list of files and folders that match this metadata query.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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" }`.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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`.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Query files/folders by metadata
tags:
- Search
x-box-enable-explorer: true
x-box-sanitized: true
x-box-tag: search
/metadata_query_indices:
get:
description: Retrieves the metadata query indices for a given scope and template key.
operationId: get_metadata_query_indices
parameters:
- description: The scope of the metadata template
example: global
in: query
name: scope
required: true
schema:
enum:
- global
- enterprise
type: string
- description: The name of the metadata template
example: properties
in: query
name: template_key
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/MetadataQueryIndices"
description: Returns a collection of metadata query indices for scope and template key.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error when any of the parameters are not in a valid format.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error when the scope and template combination cannot be found.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List metadata query indices
tags:
- Search
x-box-enable-explorer: true
x-box-sanitized: true
x-box-tag: search
/metadata_templates:
get:
description: |-
Finds a metadata template by searching for the ID of an instance of the
template.
operationId: get_metadata_templates
parameters:
- description: The ID of an instance of the metadata template to find.
example: 01234500-12f1-1234-aa12-b1d234cb567e
in: query
name: metadata_instance_id
required: true
schema:
format: uuid
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/MetadataTemplates"
description: |-
Returns a list containing the 1 metadata template that matches the
instance ID.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned when the request parameters are not valid.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Find metadata template by instance ID
tags:
- Metadata templates
x-box-sanitized: true
x-box-tag: metadata_templates
/metadata_templates/enterprise:
get:
description: |-
Used to retrieve all metadata templates created to be used specifically within
the user's enterprise
operationId: get_metadata_templates_enterprise
parameters:
- description: |-
Defines the position marker at which to begin returning results. This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
in: query
name: marker
required: false
schema:
type: string
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/MetadataTemplates"
description: |-
Returns all of the metadata templates within an enterprise
and their corresponding schema.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned when the request parameters are not valid.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List all metadata templates for enterprise
tags:
- Metadata templates
x-box-sanitized: true
x-box-tag: metadata_templates
/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema:
delete:
description: |-
Delete all classifications by deleting the classification
metadata template.
operationId: delete_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema
responses:
"204":
description: |-
Returns an empty response when the metadata
template for classifications is successfully deleted.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Delete all classifications
tags:
- Classifications
x-box-sanitized: true
x-box-tag: classifications
get:
description: |-
Retrieves the classification metadata template and lists all the
classifications available to this enterprise.
This API can also be called by including the enterprise ID in the
URL explicitly, for example
`/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`.
operationId: get_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/ClassificationTemplate"
description: |-
Returns the `securityClassification` metadata template, which contains
a `Box__Security__Classification__Key` field that lists all the
classifications available to this enterprise.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned if any of the request parameters are not valid.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when a template name is not correct. Please make sure
the URL for the request is correct.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List all classifications
tags:
- Classifications
x-box-sanitized: true
x-box-tag: classifications
/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema#add:
put:
description: |-
Adds one or more new classifications to the list of classifications
available to the enterprise.
This API can also be called by including the enterprise ID in the
URL explicitly, for example
`/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`.
operationId: put_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema#add
requestBody:
content:
application/json-patch+json:
schema:
description: |-
An array that contains one or more classifications to add to
the enterprise's list of classifications.
items:
description: A single classification to add to the enterprise.
properties:
data:
description: The details of the classification to add.
properties:
classification:
description: Additional details for the classification.
properties:
classificationDefinition:
description: A longer description of the classification.
example: Sensitive information that must not be shared.
type: string
colorID:
description: |-
An internal Box identifier used to assign a color to
a classification label.
Mapping between a `colorID` and a color may change
without notice. Currently, the color mappings are as
follows.
* `0`: Yellow
* `1`: Orange
* `2`: Watermelon red
* `3`: Purple rain
* `4`: Light blue
* `5`: Dark blue
* `6`: Light green
* `7`: Gray
example: 4
type: number
type: object
key:
description: |-
The label of the classification as shown in the web and
mobile interfaces. This is the only field required to
add a classification.
example: Sensitive
type: string
required:
- key
type: object
fieldKey:
description: "`Box__Security__Classification__Key`"
example: Box__Security__Classification__Key
type: string
op:
description: "`addEnumOption`"
example: addEnumOption
type: string
required:
- op
- fieldKey
- data
type: object
type: array
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/ClassificationTemplate"
description: |-
Returns the updated `securityClassification` metadata template, which
contains a `Box__Security__Classification__Key` field that lists all
the classifications available to this enterprise.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned if any of the request parameters are not valid.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when a template name is not correct. Please make sure
the URL for the request is correct.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Add classification
tags:
- Classifications
x-box-sanitized: true
x-box-tag: classifications
/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema#delete:
put:
description: |-
Removes a classification from the list of classifications
available to the enterprise.
This API can also be called by including the enterprise ID in the
URL explicitly, for example
`/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`.
operationId: put_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema#delete
requestBody:
content:
application/json-patch+json:
schema:
description: An array that contains one or more classifications to remove.
items:
description: A single classification to remove.
properties:
enumOptionKey:
description: The label of the classification to remove.
example: Sensitive
type: string
fieldKey:
description: "`Box__Security__Classification__Key`"
example: Box__Security__Classification__Key
type: string
op:
description: "`removeEnumOption`"
example: removeEnumOption
type: string
required:
- op
- fieldKey
- enumOptionKey
type: object
type: array
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/ClassificationTemplate"
description: |-
Returns the updated `securityClassification` metadata template, which
contains a `Box__Security__Classification__Key` field that lists all
the classifications available to this enterprise.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned if any of the request parameters are not valid.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when a template name is not correct. Please make sure
the URL for the request is correct.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Delete classification
tags:
- Classifications
x-box-sanitized: true
x-box-tag: classifications
/metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema#update:
put:
description: |-
Updates the labels and descriptions of one or more classifications
available to the enterprise.
This API can also be called by including the enterprise ID in the
URL explicitly, for example
`/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`.
operationId: put_metadata_templates_enterprise_securityClassification-6VMVochwUWo_schema#update
requestBody:
content:
application/json-patch+json:
schema:
description: An array that contains one or more classifications to update.
items:
description: A single classification to update.
properties:
data:
description: The details of the updated classification.
properties:
classification:
description: Additional details for the classification.
properties:
classificationDefinition:
description: A longer description of the classification.
example: Sensitive information that must not be shared.
type: string
colorID:
description: |-
An internal Box identifier used to assign a color to
a classification label.
Mapping between a `colorID` and a color may change
without notice. Currently, the color mappings are as
follows.
* `0`: Yellow
* `1`: Orange
* `2`: Watermelon red
* `3`: Purple rain
* `4`: Light blue
* `5`: Dark blue
* `6`: Light green
* `7`: Gray
example: 4
type: number
type: object
key:
description: |-
A new label for the classification, as it will be
shown in the web and mobile interfaces.
example: Very Sensitive
type: string
required:
- key
type: object
enumOptionKey:
description: The original label of the classification to change.
example: Sensitive
type: string
fieldKey:
description: "`Box__Security__Classification__Key`"
example: Box__Security__Classification__Key
type: string
op:
description: "`editEnumOption`"
example: editEnumOption
type: string
required:
- op
- fieldKey
- enumOptionKey
- data
type: object
type: array
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/ClassificationTemplate"
description: |-
Returns the updated `securityClassification` metadata template, which
contains a `Box__Security__Classification__Key` field that lists all
the classifications available to this enterprise.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned if any of the request parameters are not valid.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when a template name is not correct. Please make sure
the URL for the request is correct.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Update classification
tags:
- Classifications
x-box-sanitized: true
x-box-tag: classifications
/metadata_templates/global:
get:
description: |-
Used to retrieve all generic, global metadata templates available to all
enterprises using Box.
operationId: get_metadata_templates_global
parameters:
- description: |-
Defines the position marker at which to begin returning results. This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
in: query
name: marker
required: false
schema:
type: string
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/MetadataTemplates"
description: |-
Returns all of the metadata templates available to all enterprises
and their corresponding schema.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned when the request parameters are not valid.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List all global metadata templates
tags:
- Metadata templates
x-box-sanitized: true
x-box-tag: metadata_templates
/metadata_templates/schema:
post:
description: |-
Creates a new metadata template that can be applied to
files and folders.
operationId: post_metadata_templates_schema
requestBody:
content:
application/json:
schema:
properties:
copyInstanceOnItemCopy:
default: false
description: |-
Whether or not to copy any metadata attached to a file or folder
when it is copied. By default, metadata is not copied along with a
file or folder when it is copied.
example: true
type: boolean
displayName:
description: The display name of the template.
example: Product Info
maxLength: 4096
type: string
fields:
description: |-
An ordered list of template fields which are part of the template.
Each field can be a regular text field, date field, number field,
as well as a single or multi-select list.
items:
description: |-
A field within a metadata template. Fields can be a basic text, date, or
number field, or a list of options.
properties:
description:
description: A description of the field. This is not shown to the user.
example: The category
maxLength: 4096
type: string
displayName:
description: |-
The display name of the field as it is shown to the user in the web and
mobile apps.
example: Category
maxLength: 4096
type: string
hidden:
description: |-
Whether this field is hidden in the UI for the user and can only be set
through the API instead.
example: true
type: boolean
key:
description: |-
A unique identifier for the field. The identifier must
be unique within the template to which it belongs.
example: category
maxLength: 256
type: string
options:
description: |-
A list of options for this field. This is used in combination with the
`enum` and `multiSelect` field types.
items:
description: |-
An option for a Metadata Template Field.
Options only need to be provided for fields of type `enum` and `multiSelect`.
Options represent the value(s) a user can select for the field either through
the UI or through the API.
properties:
key:
description: |-
The text value of the option. This represents both the display name of the
option and the internal key used when updating templates.
example: Category 1
type: string
required:
- key
title: Metadata Option (Write)
type: object
type: array
type:
description: |-
The type of field. The basic fields are a `string` field for text, a
`float` field for numbers, and a `date` fields to present the user with a
date-time picker.
Additionally, metadata templates support an `enum` field for a basic list
of items, and ` multiSelect` field for a similar list of items where the
user can select more than one value.
enum:
- string
- float
- date
- enum
- multiSelect
example: string
type: string
required:
- type
- key
- displayName
title: Metadata Field (Write)
type: object
type: array
hidden:
default: false
description: |-
Defines if this template is visible in the Box web app UI, or if
it is purely intended for usage through the API.
example: true
type: boolean
scope:
description: |-
The scope of the metadata template to create. Applications can
only create templates for use within the authenticated user's
enterprise.
This value needs to be set to `enterprise`, as `global` scopes can
not be created by applications.
example: enterprise
type: string
templateKey:
description: |-
A unique identifier for the template. This identifier needs to be
unique across the enterprise for which the metadata template is
being created.
When not provided, the API will create a unique `templateKey`
based on the value of the `displayName`.
example: productInfo
maxLength: 64
pattern: ^[a-zA-Z_][-a-zA-Z0-9_]*$
type: string
required:
- scope
- displayName
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/MetadataTemplate"
description: The schema representing the metadata template created.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Create metadata template
tags:
- Metadata templates
x-box-requires-admin: true
x-box-sanitized: true
x-box-tag: metadata_templates
/metadata_templates/schema#classifications:
post:
description: |-
When an enterprise does not yet have any classifications, this API call
initializes the classification template with an initial set of
classifications.
If an enterprise already has a classification, the template will already
exist and instead an API call should be made to add additional
classifications.
operationId: post_metadata_templates_schema#classifications
requestBody:
content:
application/json:
schema:
properties:
copyInstanceOnItemCopy:
description: "`false`"
example: false
type: boolean
displayName:
description: "`Classification`"
enum:
- Classification
example: Classification
type: string
fields:
description: |-
The classification template holds one field, which holds
all the valid classification values.
items:
description: |-
The `enum` field which holds all the valid classification
values.
properties:
displayName:
description: "`Classification`"
enum:
- Classification
example: Classification
type: string
hidden:
description: "`false`"
example: false
type: boolean
key:
description: "`Box__Security__Classification__Key`"
enum:
- Box__Security__Classification__Key
example: Box__Security__Classification__Key
type: string
options:
description: |-
The actual list of classifications that are present on
this template.
items:
description: An individual classification.
properties:
key:
description: |-
The display name and key this classification. This
will be show in the Box UI.
example: Sensitive
type: string
staticConfig:
description: Additional information about the classification.
properties:
classification:
description: Additional information about the classification.
properties:
classificationDefinition:
description: A longer description of the classification.
example: Sensitive information
type: string
colorID:
description: |-
An identifier used to assign a color to
a classification label.
Mapping between a `colorID` and a color may
change without notice. Currently, the color
mappings are as follows.
* `0`: Yellow
* `1`: Orange
* `2`: Watermelon red
* `3`: Purple rain
* `4`: Light blue
* `5`: Dark blue
* `6`: Light green
* `7`: Gray
example: 4
type: number
type: object
type: object
type: object
type: array
type:
description: "`enum`"
enum:
- enum
example: enum
type: string
type: object
type: array
hidden:
description: "`false`"
example: false
type: boolean
scope:
description: |-
The scope in which to create the classifications. This should
be `enterprise` or `enterprise_{id}` where `id` is the unique
ID of the enterprise.
enum:
- enterprise
example: enterprise
type: string
templateKey:
description: "`securityClassification-6VMVochwUWo`"
enum:
- securityClassification-6VMVochwUWo
example: securityClassification-6VMVochwUWo
type: string
required:
- scope
- displayName
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/ClassificationTemplate"
description: |-
Returns a new `securityClassification` metadata template, which
contains a `Box__Security__Classification__Key` field that lists all
the classifications available to this enterprise.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned if any of the request parameters are not valid.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when a template name is not correct. Please make sure
the URL for the request is correct.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Add initial classifications
tags:
- Classifications
x-box-sanitized: true
x-box-tag: classifications
"/metadata_templates/{scope}/{template_key}/schema":
delete:
description: |-
Delete a metadata template and its instances.
This deletion is permanent and can not be reversed.
operationId: delete_metadata_templates_id_id_schema
parameters:
- description: The scope of the metadata template
example: global
in: path
name: scope
required: true
schema:
enum:
- global
- enterprise
type: string
- description: The name of the metadata template
example: properties
in: path
name: template_key
required: true
schema:
type: string
responses:
"204":
description: |-
Returns an empty response when the metadata
template is successfully deleted.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Request body does not contain a valid metadata schema.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Request body contains a scope that the user is not allowed to
create a template for.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Remove metadata template
tags:
- Metadata templates
x-box-sanitized: true
x-box-tag: metadata_templates
get:
description: |-
Retrieves a metadata template by its `scope` and `templateKey` values.
To find the `scope` and `templateKey` for a template, list all templates for
an enterprise or globally, or list all templates applied to a file or folder.
operationId: get_metadata_templates_id_id_schema
parameters:
- description: The scope of the metadata template
example: global
in: path
name: scope
required: true
schema:
enum:
- global
- enterprise
type: string
- description: The name of the metadata template
example: properties
in: path
name: template_key
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/MetadataTemplate"
description: |-
Returns the metadata template matching the `scope`
and `template` name.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when a template with the given `scope` and `template_key` can not
be found.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get metadata template by name
tags:
- Metadata templates
x-box-sanitized: true
x-box-tag: metadata_templates
put:
description: |-
Updates a metadata template.
The metadata template can only be updated if the template
already exists.
The update is applied atomically. If any errors occur during the
application of the operations, the metadata template will not be changed.
operationId: put_metadata_templates_id_id_schema
parameters:
- description: The scope of the metadata template
example: global
in: path
name: scope
required: true
schema:
enum:
- global
- enterprise
type: string
- description: The name of the metadata template
example: properties
in: path
name: template_key
required: true
schema:
type: string
requestBody:
content:
application/json-patch+json:
schema:
description: |-
A [JSON-Patch](https://tools.ietf.org/html/rfc6902)
specification for the changes to make to the metadata
template.
The changes are represented as a JSON array of
operation objects.
items:
description: |-
A [JSON-Patch](https://tools.ietf.org/html/rfc6902) operation for a
change to make to the metadata instance.
properties:
data:
additionalProperties:
description: The value of a custom data entry.
example: Aaron Levie
type: string
x-box-example-key: name
description: |-
The data for the operation. This will vary depending on the
operation being performed.
example:
name: Aaron Levie
type: object
enumOptionKey:
description: |-
For operations that affect a single `enum` option this defines
the key of the option that is affected.
example: option1
type: string
enumOptionKeys:
description: |-
For operations that affect multiple `enum` options this defines
the keys of the options that are affected.
example:
- option1
- option2
- option3
items:
type: string
type: array
fieldKey:
description: |-
For operations that affect a single field this defines the key of
the field that is affected.
example: category
type: string
fieldKeys:
description: |-
For operations that affect multiple fields this defines the keys
of the fields that are affected.
example:
- category
- name
items:
type: string
type: array
multiSelectOptionKey:
description: |-
For operations that affect a single multi select option this
defines the key of the option that is affected.
example: option1
type: string
multiSelectOptionKeys:
description: |-
For operations that affect multiple multi select options this
defines the keys of the options that are affected.
example:
- option1
- option2
- option3
items:
type: string
type: array
op:
description: |-
The type of change to perform on the template. Some
of these are hazardous as they will change existing templates.
enum:
- editTemplate
- addField
- reorderFields
- addEnumOption
- reorderEnumOptions
- reorderMultiSelectOptions
- addMultiSelectOption
- editField
- removeField
- editEnumOption
- removeEnumOption
- editMultiSelectOption
- removeMultiSelectOption
example: addEnumOption
type: string
required:
- op
title: A metadata template update operation
type: object
type: array
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/MetadataTemplate"
description: |-
Returns the updated metadata template, with the
custom template data included.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: The request body does not contain a valid metadata schema.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
The request body contains a scope that the user is not
allowed to create templates for.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: The requested template could not be found
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Update metadata template
tags:
- Metadata templates
x-box-sanitized: true
x-box-tag: metadata_templates
"/metadata_templates/{template_id}":
get:
description: Retrieves a metadata template by its ID.
operationId: get_metadata_templates_id
parameters:
- description: The ID of the template
example: f7a9891f
in: path
name: template_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/MetadataTemplate"
description: Returns the metadata template that matches the ID.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/MetadataTemplate"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get metadata template by ID
tags:
- Metadata templates
x-box-sanitized: true
x-box-tag: metadata_templates
/oauth2/revoke:
post:
description: |-
Revoke an active Access Token, effectively logging a user out
that has been previously authenticated.
operationId: post_oauth2_revoke
requestBody:
content:
application/x-www-form-urlencoded:
schema:
$ref: "#/components/schemas/PostOAuth2Revoke"
responses:
"200":
description: Returns an empty response when the token was successfully revoked.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/OAuth2Error"
description: An authentication error.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/OAuth2Error"
description: An authentication error.
security: []
servers:
- description: Server for server-side authentication
url: https://api.box.com
summary: Revoke access token
tags:
- Authorization
x-box-tag: authorization
/oauth2/token:
post:
description: |-
Request an Access Token using either a client-side obtained OAuth 2.0
authorization code or a server-side JWT assertion.
An Access Token is a string that enables Box to verify that a
request belongs to an authorized session. In the normal order of
operations you will begin by requesting authentication from the
[authorize](#get-authorize) endpoint and Box will send you an
authorization code.
You will then send this code to this endpoint to exchange it for
an Access Token. The returned Access Token can then be used to to make
Box API calls.
operationId: post_oauth2_token
requestBody:
content:
application/x-www-form-urlencoded:
schema:
$ref: "#/components/schemas/PostOAuth2Token"
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/AccessToken"
description: |-
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 `.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/OAuth2Error"
description: An authentication error.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/OAuth2Error"
description: An authentication error.
security: []
servers:
- description: Server for server-side authentication
url: https://api.box.com
summary: Request access token
tags:
- Authorization
x-box-tag: authorization
/oauth2/token#refresh:
post:
description: Refresh an Access Token using its client ID, secret, and refresh token.
operationId: post_oauth2_token#refresh
requestBody:
content:
application/x-www-form-urlencoded:
schema:
$ref: "#/components/schemas/PostOAuth2Token--RefreshAccessToken"
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/AccessToken"
description: |-
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 `.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/OAuth2Error"
description: An authentication error.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/OAuth2Error"
description: An authentication error.
security: []
servers:
- description: Server for server-side authentication
url: https://api.box.com
summary: Refresh access token
tags:
- Authorization
x-box-is-variation: true
x-box-tag: authorization
/recent_items:
get:
description: |-
Returns information about the recent items accessed
by a user, either in the last 90 days or up to the last
1000 items accessed.
operationId: get_recent_items
parameters:
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
- description: |-
Defines the position marker at which to begin returning results. This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
in: query
name: marker
required: false
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/RecentItems"
description: Returns a list recent items access by a user.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List recently accessed items
tags:
- Recent items
x-box-enable-explorer: true
x-box-tag: recent_items
/retention_policies:
get:
description: Retrieves all of the retention policies for an enterprise.
operationId: get_retention_policies
parameters:
- description: |-
Filters results by a case sensitive prefix of the name of
retention policies.
example: Sales Policy
in: query
name: policy_name
required: false
schema:
type: string
- description: Filters results by the type of retention policy.
example: finite
in: query
name: policy_type
required: false
schema:
enum:
- finite
- indefinite
type: string
- description: Filters results by the ID of the user who created policy.
example: "21312321"
in: query
name: created_by_user_id
required: false
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
- description: |-
Defines the position marker at which to begin returning results. This is
used when paginating using marker-based pagination.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
in: query
name: marker
required: false
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/RetentionPolicies"
description: Returns a list retention policies in the enterprise.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns a `bad_request` if a non existent `policy_type` was specified.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns a `not_found` error if the user specified in `created_by_user_id`
does not exist.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List retention policies
tags:
- Retention policies
x-box-tag: retention_policies
post:
description: Creates a retention policy.
operationId: post_retention_policies
requestBody:
content:
application/json:
schema:
properties:
are_owners_notified:
description: |-
Whether owner and co-owners of a file are notified
when the policy nears expiration.
enum:
- true
- false
example: true
type: boolean
can_owner_extend_retention:
description: |-
Whether the owner of a file will be allowed to
extend the retention.
enum:
- true
- false
example: true
type: boolean
custom_notification_recipients:
description: |-
A list of users notified when
the retention policy duration is about to end.
items:
$ref: "#/components/schemas/User--Mini"
type: array
description:
description: The additional text description of the retention policy.
example: Policy to retain all reports for at least one month
type: string
disposition_action:
description: |-
The disposition action of the retention policy.
`permanently_delete` deletes the content
retained by the policy permanently.
`remove_retention` lifts retention policy
from the content, allowing it to be deleted
by users once the retention policy has expired.
enum:
- permanently_delete
- remove_retention
example: permanently_delete
type: string
policy_name:
description: The name for the retention policy
example: Some Policy Name
type: string
policy_type:
description: |-
The type of the retention policy. A retention
policy type can either be `finite`, where a
specific amount of time to retain the content is known
upfront, or `indefinite`, where the amount of time
to retain the content is still unknown.
enum:
- finite
- indefinite
example: finite
type: string
retention_length:
description: |-
The length of the retention policy. This value
specifies the duration in days that the retention
policy will be active for after being assigned to
content. If the policy has a `policy_type` of
`indefinite`, the `retention_length` will also be
`indefinite`.
example: "365"
format: int32
minimum: 1
type: string
retention_type:
description: |-
Specifies the retention type:
* `modifiable`: You can modify the retention policy. For example,
you can add or remove folders, shorten or lengthen
the policy duration, or delete the assignment.
Use this type if your retention policy
is not related to any regulatory purposes.
* `non-modifiable`: You can modify the retention policy
only in a limited way: add a folder, lengthen the duration,
retire the policy, change the disposition action
or notification settings. You cannot perform other actions,
such as deleting the assignment or shortening the
policy duration. Use this type to ensure
compliance with regulatory retention policies.
enum:
- modifiable
- non-modifiable
example: modifiable
type: string
required:
- policy_name
- policy_type
- disposition_action
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/RetentionPolicy"
description: Returns a new retention policy object.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns a `bad_request` error with the `retention_length` was
specified for a `infinite` retention policy, an incorrect
`disposition_action` was set, or description exceeds maximum length of
500 characters.
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if a retention policy with the given name already exists
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Create retention policy
tags:
- Retention policies
x-box-tag: retention_policies
"/retention_policies/{retention_policy_id}":
delete:
description: Permanently deletes a retention policy.
operationId: delete_retention_policies_id
parameters:
- description: The ID of the retention policy.
example: "982312"
in: path
name: retention_policy_id
required: true
schema:
type: string
responses:
"204":
description: Returns an empty response when the policy has been deleted.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if the policy is non-modifiable or the user does
not have the required access to perform the action.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if the policy is not found.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Delete retention policy
tags:
- Retention policies
x-box-scopes:
- manage_data_retention
- data_retention
x-box-tag: retention_policies
get:
description: Retrieves a retention policy.
operationId: get_retention_policies_id
parameters:
- description: The ID of the retention policy.
example: "982312"
in: path
name: retention_policy_id
required: true
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/RetentionPolicy"
description: Returns the retention policy object.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get retention policy
tags:
- Retention policies
x-box-tag: retention_policies
put:
description: Updates a retention policy.
operationId: put_retention_policies_id
parameters:
- description: The ID of the retention policy.
example: "982312"
in: path
name: retention_policy_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
are_owners_notified:
description: |-
Determines if owners and co-owners of items
under the policy are notified when
the retention duration is about to end.
enum:
- true
- false
example: false
type: boolean
can_owner_extend_retention:
description: |-
Determines if the owner of items under the policy
can extend the retention when the original retention
duration is about to end.
example: false
type: boolean
custom_notification_recipients:
description: A list of users notified when the retention duration is about to end.
items:
$ref: "#/components/schemas/User--Mini"
type: array
description:
description: The additional text description of the retention policy.
example: Policy to retain all reports for at least one month
type: string
disposition_action:
description: |-
The disposition action of the retention policy.
`permanently_delete` deletes the content
retained by the policy permanently.
`remove_retention` lifts retention policy
from the content, allowing it to be deleted
by users once the retention policy has expired.
enum:
- permanently_delete
- remove_retention
example: permanently_delete
type: string
policy_name:
description: The name for the retention policy
example: Some Policy Name
type: string
retention_length:
description: |-
The length of the retention policy. This value
specifies the duration in days that the retention
policy will be active for after being assigned to
content. If the policy has a `policy_type` of
`indefinite`, the `retention_length` will also be
`indefinite`.
example: "365"
format: int32
type: string
retention_type:
description: |-
Specifies the retention type:
* `modifiable`: You can modify the retention policy. For example,
you can add or remove folders, shorten or lengthen
the policy duration, or delete the assignment.
Use this type if your retention policy
is not related to any regulatory purposes.
* `non-modifiable`: You can modify the retention policy
only in a limited way: add a folder, lengthen the duration,
retire the policy, change the disposition action
or notification settings. You cannot perform other actions,
such as deleting the assignment or shortening the
policy duration. Use this type to ensure
compliance with regulatory retention policies.
When updating a retention policy, you can use
`non-modifiable` type only. You can convert a
`modifiable` policy to `non-modifiable`, but
not the other way around.
example: non-modifiable
type: string
status:
description: |-
Used to retire a retention policy.
If not retiring a policy, do not include this parameter
or set it to `null`.
example: retired
type: string
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/RetentionPolicy"
description: Returns the updated retention policy object.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns a `bad_request` if an incorrect
`disposition_action` was set or description exceeds maximum length of
500 characters.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if a retention policy with the given name already exists
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Update retention policy
tags:
- Retention policies
x-box-tag: retention_policies
"/retention_policies/{retention_policy_id}/assignments":
get:
description: |-
Returns a list of all retention policy assignments associated with a specified
retention policy.
operationId: get_retention_policies_id_assignments
parameters:
- description: The ID of the retention policy.
example: "982312"
in: path
name: retention_policy_id
required: true
schema:
type: string
- description: The type of the retention policy assignment to retrieve.
example: metadata_template
in: query
name: type
required: false
schema:
enum:
- folder
- enterprise
- metadata_template
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
- description: |-
Defines the position marker at which to begin returning results. This is
used when paginating using marker-based pagination.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
in: query
name: marker
required: false
schema:
type: string
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/RetentionPolicyAssignments"
description: |-
Returns a list of the retention policy assignments associated with the
specified retention policy.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if an unknown `type` is specified.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List retention policy assignments
tags:
- Retention policy assignments
x-box-tag: retention_policy_assignments
/retention_policy_assignments:
post:
description: Assigns a retention policy to an item.
operationId: post_retention_policy_assignments
requestBody:
content:
application/json:
schema:
properties:
assign_to:
description: The item to assign the policy to
properties:
id:
description: |-
The ID of item to assign the policy to.
Set to `null` or omit when `type` is set to
`enterprise`.
example: "6564564"
type: string
type:
description: The type of item to assign the policy to.
enum:
- enterprise
- folder
- metadata_template
example: metadata_template
type: string
required:
- type
- id
type: object
filter_fields:
description: |-
If the `assign_to` type is `metadata_template`,
then optionally add the `filter_fields` parameter which will
require an array of objects with a field entry and a value entry.
Currently only one object of `field` and `value` is supported.
items:
properties:
field:
description: The metadata attribute key id.
example: a0f4ee4e-1dc1-4h90-a8a9-aef55fc681d4
type: string
value:
description: |-
The metadata attribute field id. For value, only
enum and multiselect types are supported.
example: 0c27b756-0p87-4fe0-a43a-59fb661ccc4e
type: string
type: object
type: array
policy_id:
description: The ID of the retention policy to assign
example: "173463"
type: string
start_date_field:
description: |-
The date the retention policy assignment begins.
If the `assigned_to` type is `metadata_template`,
this field can be a date field's metadata attribute key id.
example: upload_date
type: string
required:
- policy_id
- assign_to
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/RetentionPolicyAssignment"
description: Returns a new retention policy assignment object.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if no retention policy with the given `policy_id` exists.
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if a retention policy of equal or greater length has
already been assigned to this item.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Assign retention policy
tags:
- Retention policy assignments
x-box-tag: retention_policy_assignments
"/retention_policy_assignments/{retention_policy_assignment_id}":
delete:
description: |-
Removes a retention policy assignment
applied to content.
operationId: delete_retention_policy_assignments_id
parameters:
- description: The ID of the retention policy assignment.
example: "1233123"
in: path
name: retention_policy_assignment_id
required: true
schema:
type: string
responses:
"204":
description: |-
Returns an empty response when the policy assignment
is successfully deleted.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error when the assignment relates to
a retention policy that cannot be modified.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error when the retention policy
assignment does not exist.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Remove retention policy assignment
tags:
- Retention policy assignments
x-box-tag: retention_policy_assignments
get:
description: Retrieves a retention policy assignment
operationId: get_retention_policy_assignments_id
parameters:
- description: The ID of the retention policy assignment.
example: "1233123"
in: path
name: retention_policy_assignment_id
required: true
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/RetentionPolicyAssignment"
description: Returns the retention policy assignment object.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get retention policy assignment
tags:
- Retention policy assignments
x-box-tag: retention_policy_assignments
"/retention_policy_assignments/{retention_policy_assignment_id}/file_versions_under_retention":
get:
description: |-
Returns a list of file versions under retention for a retention policy
assignment.
operationId: get_retention_policy_assignments_id_file_versions_under_retention
parameters:
- description: The ID of the retention policy assignment.
example: "1233123"
in: path
name: retention_policy_assignment_id
required: true
schema:
type: string
- description: |-
Defines the position marker at which to begin returning results. This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
in: query
name: marker
required: false
schema:
type: string
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/FilesUnderRetention"
description: |-
Returns a list of file versions under retention that are associated with
the specified retention policy assignment.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if `retention_policy_assignment_id` is not specified.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get file versions under retention
tags:
- Retention policy assignments
x-box-tag: retention_policy_assignments
"/retention_policy_assignments/{retention_policy_assignment_id}/files_under_retention":
get:
description: Returns a list of files under retention for a retention policy assignment.
operationId: get_retention_policy_assignments_id_files_under_retention
parameters:
- description: The ID of the retention policy assignment.
example: "1233123"
in: path
name: retention_policy_assignment_id
required: true
schema:
type: string
- description: |-
Defines the position marker at which to begin returning results. This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
in: query
name: marker
required: false
schema:
type: string
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/FilesUnderRetention"
description: |-
Returns a list of files under retention that are associated with the
specified retention policy assignment.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if `retention_policy_assignment_id` is not specified.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get files under retention
tags:
- Retention policy assignments
x-box-tag: retention_policy_assignments
/search:
get:
description: |-
Searches for files, folders, web links, and shared files across the
users content or across the entire enterprise.
operationId: get_search
parameters:
- description: |-
The string to search for. This query is matched against item names,
descriptions, text content of files, and various other fields of
the different item types.
This parameter supports a variety of operators to further refine
the results returns.
* `""` - by wrapping a query in double quotes only exact matches are
returned by the API. Exact searches do not return search matches
based on specific character sequences. Instead, they return
matches based on phrases, that is, word sequences. For example:
A search for `"Blue-Box"` may return search results including
the sequence `"blue.box"`, `"Blue Box"`, and `"Blue-Box"`;
any item containing the words `Blue` and `Box` consecutively, in
the order specified.
* `AND` - returns items that contain both the search terms. For
example, a search for `marketing AND BoxWorks` returns items
that have both `marketing` and `BoxWorks` within its text in any order.
It does not return a result that only has `BoxWorks` in its text.
* `OR` - returns items that contain either of the search terms. For
example, a search for `marketing OR BoxWorks` returns a result that
has either `marketing` or `BoxWorks` within its text. Using this
operator is not necessary as we implicitly interpret multi-word
queries as `OR` unless another supported boolean term is used.
* `NOT` - returns items that do not contain the search term provided.
For example, a search for `marketing AND NOT BoxWorks` returns a result
that has only `marketing` within its text. Results containing
`BoxWorks` are omitted.
We do not support lower case (that is,
`and`, `or`, and `not`) or mixed case (that is, `And`, `Or`, and `Not`)
operators.
This field is required unless the `mdfilters` parameter is defined.
example: sales
in: query
name: query
required: false
schema:
type: string
- description: |-
Limits the search results to either the files that the user has
access to, or to files available to the entire enterprise.
The scope defaults to `user_content`, which limits the search
results to content that is available to the currently authenticated
user.
The `enterprise_content` can be requested by an admin through our
support channels. Once this scope has been enabled for a user, it
will allow that use to query for content across the entire
enterprise and not only the content that they have access to.
example: user_content
in: query
name: scope
required: false
schema:
default: user_content
enum:
- user_content
- enterprise_content
type: string
- description: |-
Limits the search results to any files that match any of the provided
file extensions. This list is a comma-separated list of file extensions
without the dots.
example:
- pdf
- png
- gif
explode: false
in: query
name: file_extensions
required: false
schema:
items:
type: string
type: array
- description: |-
Limits the search results to any items created within
a given date range.
Date ranges are defined as comma separated RFC3339
timestamps.
If the the start date is omitted (`,2014-05-17T13:35:01-07:00`)
anything created before the end date will be returned.
If the end date is omitted (`2014-05-15T13:35:01-07:00,`) the
current date will be used as the end date instead.
example:
- 2014-05-15T13:35:01-07:00
- 2014-05-17T13:35:01-07:00
explode: false
in: query
name: created_at_range
required: false
schema:
items:
type: string
type: array
- description: |-
Limits the search results to any items updated within
a given date range.
Date ranges are defined as comma separated RFC3339
timestamps.
If the start date is omitted (`,2014-05-17T13:35:01-07:00`)
anything updated before the end date will be returned.
If the end date is omitted (`2014-05-15T13:35:01-07:00,`) the
current date will be used as the end date instead.
example:
- 2014-05-15T13:35:01-07:00
- 2014-05-17T13:35:01-07:00
explode: false
in: query
name: updated_at_range
required: false
schema:
items:
type: string
type: array
- description: |-
Limits the search results to any items with a size within
a given file size range. This applied to files and folders.
Size ranges are defined as comma separated list of a lower
and upper byte size limit (inclusive).
The upper and lower bound can be omitted to create open ranges.
example:
- 1000000
- 5000000
explode: false
in: query
name: size_range
required: false
schema:
items:
type: integer
type: array
- description: |-
Limits the search results to any items that are owned
by the given list of owners, defined as a list of comma separated
user IDs.
The items still need to be owned or shared with
the currently authenticated user for them to show up in the search
results. If the user does not have access to any files owned by any of
the users an empty result set will be returned.
To search across an entire enterprise, we recommend using the
`enterprise_content` scope parameter which can be requested with our
support team.
example:
- "123422"
- "23532"
- "3241212"
explode: false
in: query
name: owner_user_ids
required: false
schema:
items:
type: string
type: array
- description: |-
Limits the search results to any items that have been updated
by the given list of users, defined as a list of comma separated
user IDs.
The items still need to be owned or shared with
the currently authenticated user for them to show up in the search
results. If the user does not have access to any files owned by any of
the users an empty result set will be returned.
This feature only searches back to the last 10 versions of an item.
example:
- "123422"
- "23532"
- "3241212"
explode: false
in: query
name: recent_updater_user_ids
required: false
schema:
items:
type: string
type: array
- description: |-
Limits the search results to items within the given
list of folders, defined as a comma separated lists
of folder IDs.
Search results will also include items within any subfolders
of those ancestor folders.
The folders still need to be owned or shared with
the currently authenticated user. If the folder is not accessible by this
user, or it does not exist, a `HTTP 404` error code will be returned
instead.
To search across an entire enterprise, we recommend using the
`enterprise_content` scope parameter which can be requested with our
support team.
example:
- "4535234"
- "234123235"
- "2654345"
explode: false
in: query
name: ancestor_folder_ids
required: false
schema:
items:
type: string
type: array
- description: |-
Limits the search results to any items that match the search query
for a specific part of the file, for example the file description.
Content types are defined as a comma separated lists
of Box recognized content types. The allowed content types are as follows.
* `name` - The name of the item, as defined by its `name` field.
* `description` - The description of the item, as defined by its
`description` field.
* `file_content` - The actual content of the file.
* `comments` - The content of any of the comments on a file or
folder.
* `tags` - Any tags that are applied to an item, as defined by its
`tags` field.
example:
- name
- description
explode: false
in: query
name: content_types
required: false
schema:
items:
enum:
- name
- description
- file_content
- comments
- tag
type: string
type: array
- description: |-
Limits the search results to any items of this type. This
parameter only takes one value. By default the API returns
items that match any of these types.
* `file` - Limits the search results to files
* `folder` - Limits the search results to folders
* `web_link` - Limits the search results to web links, also known
as bookmarks
example: file
in: query
name: type
required: false
schema:
enum:
- file
- folder
- web_link
type: string
- description: |-
Determines if the search should look in the trash for items.
By default, this API only returns search results for items
not currently in the trash (`non_trashed_only`).
* `trashed_only` - Only searches for items currently in the trash
* `non_trashed_only` - Only searches for items currently not in
the trash
example: non_trashed_only
in: query
name: trash_content
required: false
schema:
default: non_trashed_only
enum:
- non_trashed_only
- trashed_only
type: string
- description: |-
Limits the search results to any items for which the metadata matches
the provided filter.
This parameter contains a list of 1 metadata template to filter
the search results by. This list can currently only
contain one entry, though this might be expanded in the future.
This parameter is required unless the `query` parameter is provided.
example:
- filters:
category: online
scope: enterprise
templateKey: contract
in: query
name: mdfilters
required: false
schema:
description: |-
A list of metadata templates to filter the search results by.
Required unless `query` parameter is defined.
items:
$ref: "#/components/schemas/MetadataFilter"
maxItems: 1
minItems: 1
type: array
x-example:
- filters:
category: online
contractValue: 1000000
scope: enterprise
templateKey: contract
- description: |-
Defines the order in which search results are returned. This API
defaults to returning items by relevance unless this parameter is
explicitly specified.
* `relevance` (default) returns the results sorted by relevance to the
query search term. The relevance is based on the occurrence of the search
term in the items name, description, content, and additional properties.
* `modified_at` returns the results ordered in descending order by date
at which the item was last modified.
example: modified_at
in: query
name: sort
required: false
schema:
default: relevance
enum:
- modified_at
- relevance
type: string
- description: |-
Defines the direction in which search results are ordered. This API
defaults to returning items in descending (`DESC`) order unless this
parameter is explicitly specified.
When results are sorted by `relevance` the ordering is locked to returning
items in descending order of relevance, and this parameter is ignored.
example: ASC
in: query
name: direction
required: false
schema:
default: DESC
enum:
- DESC
- ASC
type: string
- description: |-
Defines the maximum number of items to return as part of a page of
results.
example: 100
in: query
name: limit
required: false
schema:
default: 30
format: int64
maximum: 200
type: integer
- description: |-
Defines whether the search results should include any items
that the user recently accessed through a shared link.
When this parameter has been set to true,
the format of the response of this API changes to return
a list of [Search Results with
Shared Links](r://search_results_with_shared_links)
example: true
in: query
name: include_recent_shared_links
required: false
schema:
default: false
type: boolean
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
- description: |-
The offset of the item at which to begin the response.
Queries with offset parameter value
exceeding 10000 will be rejected
with a 400 response.
example: 1000
in: query
name: offset
required: false
schema:
default: 0
format: int64
type: integer
- description: |-
Limits the search results to items that were deleted by the given
list of users, defined as a list of comma separated user IDs.
The `trash_content` parameter needs to be set to `trashed_only`.
If searching in trash is not performed, an empty result set
is returned. The items need to be owned or shared with
the currently authenticated user for them to show up in the search
results.
If the user does not have access to any files owned by
any of the users, an empty result set is returned.
Data available from 2023-02-01 onwards.
example:
- "123422"
- "23532"
- "3241212"
in: query
name: deleted_user_ids
required: false
schema:
items:
type: string
type: array
- description: |-
Limits the search results to any items deleted within a given
date range.
Date ranges are defined as comma separated RFC3339 timestamps.
If the the start date is omitted (`2014-05-17T13:35:01-07:00`),
anything deleted before the end date will be returned.
If the end date is omitted (`2014-05-15T13:35:01-07:00`),
the current date will be used as the end date instead.
The `trash_content` parameter needs to be set to `trashed_only`.
If searching in trash is not performed, then an empty result
is returned.
Data available from 2023-02-01 onwards.
example:
- 2014-05-15T13:35:01-07:00
- 2014-05-17T13:35:01-07:00
in: query
name: deleted_at_range
required: false
schema:
items:
type: string
type: array
responses:
"200":
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/SearchResults"
- $ref: "#/components/schemas/SearchResultsWithSharedLinks"
description: |-
Returns a collection of search results. If there are no matching
search results, the `entries` array will be empty.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Search for content
tags:
- Search
x-box-enable-explorer: true
x-box-tag: search
/shared_items:
get:
description: |-
Returns the file represented by a shared link.
A shared file can be represented by a shared link,
which can originate within the current enterprise or within another.
This endpoint allows an application to retrieve information about a
shared file when only given a shared link.
The `shared_link_permission_options` array field can be returned
by requesting it in the `fields` query parameter.
operationId: get_shared_items
parameters:
- description: |-
Ensures an item is only returned if it has changed.
Pass in the item's last observed `etag` value
into this header and the endpoint will fail
with a `304 Not Modified` if the item has not
changed since.
example: "1"
in: header
name: if-none-match
required: false
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
- description: |-
A header containing the shared link and optional password for the
shared link.
The format for this header is as follows.
`shared_link=[link]&shared_link_password=[password]`
example: shared_link=[link]&shared_link_password=[password]
in: header
name: boxapi
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/File--Full"
description: |-
Returns a full file resource if the shared link is valid and
the user has access to it.
"304":
description: |-
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:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Find file for shared link
tags:
- Shared links (Files)
x-box-enable-explorer: true
x-box-tag: shared_links_files
/shared_items#folders:
get:
description: |-
Return the folder represented by a shared link.
A shared folder can be represented by a shared link,
which can originate within the current enterprise or within another.
This endpoint allows an application to retrieve information about a
shared folder when only given a shared link.
operationId: get_shared_items#folders
parameters:
- description: |-
Ensures an item is only returned if it has changed.
Pass in the item's last observed `etag` value
into this header and the endpoint will fail
with a `304 Not Modified` if the item has not
changed since.
example: "1"
in: header
name: if-none-match
required: false
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
- description: |-
A header containing the shared link and optional password for the
shared link.
The format for this header is as follows.
`shared_link=[link]&shared_link_password=[password]`
example: shared_link=[link]&shared_link_password=[password]
in: header
name: boxapi
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Folder--Full"
description: |-
Returns a full folder resource if the shared link is valid and
the user has access to it.
"304":
description: |-
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:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Find folder for shared link
tags:
- Shared links (Folders)
x-box-enable-explorer: true
x-box-tag: shared_links_folders
/shared_items#web_links:
get:
description: |-
Returns the web link represented by a shared link.
A shared web link can be represented by a shared link,
which can originate within the current enterprise or within another.
This endpoint allows an application to retrieve information about a
shared web link when only given a shared link.
operationId: get_shared_items#web_links
parameters:
- description: |-
Ensures an item is only returned if it has changed.
Pass in the item's last observed `etag` value
into this header and the endpoint will fail
with a `304 Not Modified` if the item has not
changed since.
example: "1"
in: header
name: if-none-match
required: false
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
- description: |-
A header containing the shared link and optional password for the
shared link.
The format for this header is as follows.
`shared_link=[link]&shared_link_password=[password]`
example: shared_link=[link]&shared_link_password=[password]
in: header
name: boxapi
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/WebLink"
description: |-
Returns a full file resource if the shared link is valid and
the user has access to it.
"304":
description: |-
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:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Find web link for shared link
tags:
- Shared links (Web Links)
x-box-enable-explorer: true
x-box-tag: shared_links_web_links
/shield_information_barrier_reports:
get:
description: Lists shield information barrier reports with specific IDs.
operationId: get_shield_information_barrier_reports
parameters:
- description: The ID of the shield information barrier.
example: "1910967"
in: query
name: shield_information_barrier_id
required: true
schema:
type: string
- description: |-
Defines the position marker at which to begin returning results. This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
in: query
name: marker
required: false
schema:
type: string
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
responses:
"200":
content:
application/json:
schema:
properties:
entries:
description: A list of shield barrier reports.
items:
$ref: "#/components/schemas/ShieldInformationBarrierReport"
type: array
limit:
description: |-
The limit that was used for these entries.
This will be the same as the
`limit` query parameter unless that
value exceeded the maximum value
allowed. The maximum value varies by API.
example: 1000
format: int64
type: integer
next_marker:
description: The marker for the start of the next page of results.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
type: string
type: object
description: Returns a paginated list of shield information barrier report objects.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns a `not_found` error if the
shield information barrier was not found.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List shield information barrier reports
tags:
- Shield information barrier reports
x-box-scopes:
- manage_managed_users
x-box-tag: shield_information_barrier_reports
post:
description: Creates a shield information barrier report for a given barrier.
operationId: post_shield_information_barrier_reports
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/ShieldInformationBarrierReference"
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/ShieldInformationBarrierReport"
description: Returns the shield information barrier report information object.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns a `not_found` error if
the shield information barrier report was not found.
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns a `conflict` error if a
shield information barrier report is currently being created.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Create shield information barrier report
tags:
- Shield information barrier reports
x-box-scopes:
- manage_managed_users
x-box-tag: shield_information_barrier_reports
"/shield_information_barrier_reports/{shield_information_barrier_report_id}":
get:
description: Retrieves a shield information barrier report by its ID.
operationId: get_shield_information_barrier_reports_id
parameters:
- description: The ID of the shield information barrier Report.
example: "3423"
in: path
name: shield_information_barrier_report_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/ShieldInformationBarrierReport"
description: Returns the shield information barrier report object.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns a `not_found` error if the
shield information barrier Report was not found.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get shield information barrier report by ID
tags:
- Shield information barrier reports
x-box-scopes:
- manage_managed_users
x-box-tag: shield_information_barrier_reports
/shield_information_barrier_segment_members:
get:
description: |-
Lists shield information barrier segment members
based on provided segment IDs.
operationId: get_shield_information_barrier_segment_members
parameters:
- description: The ID of the shield information barrier segment.
example: "3423"
in: query
name: shield_information_barrier_segment_id
required: true
schema:
type: string
- description: |-
Defines the position marker at which to begin returning results. This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
in: query
name: marker
required: false
schema:
type: string
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
responses:
"200":
content:
application/json:
schema:
properties:
entries:
items:
$ref: "#/components/schemas/ShieldInformationBarrierSegmentMember"
type: array
limit:
description: |-
The limit that was used for these entries.
This will be the same as the
`limit` query parameter unless that value
exceeded the maximum value
allowed. The maximum value varies by API.
example: 1000
format: int64
type: integer
next_marker:
description: The marker for the start of the next page of results.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
type: string
type: object
description: |-
Returns a paginated list of
shield information barrier segment member objects.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List shield information barrier segment members
tags:
- Shield information barrier segment members
x-box-scopes:
- manage_managed_users
x-box-tag: shield_information_barrier_segment_members
post:
description: Creates a new shield information barrier segment member.
operationId: post_shield_information_barrier_segment_members
requestBody:
content:
application/json:
schema:
properties:
shield_information_barrier:
$ref: "#/components/schemas/ShieldInformationBarrier--Base"
shield_information_barrier_segment:
description: |-
The `type` and `id` of the
requested shield information barrier segment.
properties:
id:
description: |-
The ID reference of the
requesting shield information barrier segment.
example: "432554"
type: string
type:
description: The type of the shield barrier segment for this member.
enum:
- shield_information_barrier_segment
example: shield_information_barrier_segment
type: string
type: object
type:
description: -| A type of the shield barrier segment member.
enum:
- shield_information_barrier_segment_member
example: shield_information_barrier_segment_member
type: string
user:
allOf:
- $ref: "#/components/schemas/User--Base"
- description: The `type` and `id` of the requested shield information barrier segment Member.
required:
- shield_information_barrier_segment
- user
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/ShieldInformationBarrierSegmentMember"
description: Returns a new shield information barrier segment Member object.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if the
shield information barrier or Segment was not found.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Create shield information barrier segment member
tags:
- Shield information barrier segment members
x-box-scopes:
- manage_managed_users
x-box-tag: shield_information_barrier_segment_members
"/shield_information_barrier_segment_members/{shield_information_barrier_segment_member_id}":
delete:
description: |-
Deletes a shield information barrier
segment member based on provided ID.
operationId: delete_shield_information_barrier_segment_members_id
parameters:
- description: The ID of the shield information barrier segment Member.
example: "7815"
in: path
name: shield_information_barrier_segment_member_id
required: true
schema:
type: string
responses:
"204":
description: |-
Returns an empty response if the
segment member was deleted successfully.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns a `not_found` error if the
shield information barrier segment member was not found.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Delete shield information barrier segment member by ID
tags:
- Shield information barrier segment members
x-box-scopes:
- manage_managed_users
x-box-tag: shield_information_barrier_segment_members
get:
description: |-
Retrieves a shield information barrier
segment member by its ID.
operationId: get_shield_information_barrier_segment_members_id
parameters:
- description: The ID of the shield information barrier segment Member.
example: "7815"
in: path
name: shield_information_barrier_segment_member_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/ShieldInformationBarrierSegmentMember"
description: Returns the shield information barrier segment member object.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns a `not_found` error if
the shield information barrier segment member was not found.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get shield information barrier segment member by ID
tags:
- Shield information barrier segment members
x-box-scopes:
- manage_managed_users
x-box-tag: shield_information_barrier_segment_members
/shield_information_barrier_segment_restrictions:
get:
description: |-
Lists shield information barrier segment restrictions
based on provided segment ID.
operationId: get_shield_information_barrier_segment_restrictions
parameters:
- description: The ID of the shield information barrier segment.
example: "3423"
in: query
name: shield_information_barrier_segment_id
required: true
schema:
type: string
- description: |-
Defines the position marker at which to begin returning results. This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
in: query
name: marker
required: false
schema:
type: string
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
responses:
"200":
content:
application/json:
schema:
properties:
entries:
items:
$ref: "#/components/schemas/ShieldInformationBarrierSegmentRestriction"
type: array
limit:
description: |-
The limit that was used for these entries.
This will be the same as the
`limit` query parameter unless
that value exceeded the maximum value
allowed. The maximum value varies by API.
example: 1000
format: int64
type: integer
next_marker:
description: The marker for the start of the next page of results.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
type: string
type: object
description: |-
Returns a paginated list of
shield information barrier segment restriction objects.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List shield information barrier segment restrictions
tags:
- Shield information barrier segment restrictions
x-box-scopes:
- manage_managed_users
x-box-tag: shield_information_barrier_segment_restrictions
post:
description: |-
Creates a shield information barrier
segment restriction object.
operationId: post_shield_information_barrier_segment_restrictions
requestBody:
content:
application/json:
schema:
properties:
restricted_segment:
description: |-
The `type` and `id` of the restricted
shield information barrier segment.
properties:
id:
description: |-
The ID reference of the restricted
shield information barrier segment.
example: "1910967"
type: string
type:
description: |-
The type of the restricted shield
information barrier segment.
enum:
- shield_information_barrier_segment
example: shield_information_barrier_segment
type: string
type: object
shield_information_barrier:
$ref: "#/components/schemas/ShieldInformationBarrier--Base"
shield_information_barrier_segment:
description: |-
The `type` and `id` of the requested
shield information barrier segment.
properties:
id:
description: |-
The ID reference of the requesting
shield information barrier segment.
example: "1910967"
type: string
type:
description: The type of the shield barrier segment for this member.
enum:
- shield_information_barrier_segment
example: shield_information_barrier_segment
type: string
type: object
type:
description: |-
The type of the shield barrier segment
restriction for this member.
enum:
- shield_information_barrier_segment_restriction
example: shield_information_barrier_segment_restriction
type: string
required:
- type
- shield_information_barrier_segment
- restricted_segment
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/ShieldInformationBarrierSegmentRestriction"
description: |-
Returns the newly created Shield
Information Barrier Segment Restriction object.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns a `not_found` error if the
shield information barrier or Segment was not found.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Create shield information barrier segment restriction
tags:
- Shield information barrier segment restrictions
x-box-scopes:
- manage_managed_users
x-box-tag: shield_information_barrier_segment_restrictions
"/shield_information_barrier_segment_restrictions/{shield_information_barrier_segment_restriction_id}":
delete:
description: |-
Delete shield information barrier segment restriction
based on provided ID.
operationId: delete_shield_information_barrier_segment_restrictions_id
parameters:
- description: The ID of the shield information barrier segment Restriction.
example: "4563"
in: path
name: shield_information_barrier_segment_restriction_id
required: true
schema:
type: string
responses:
"204":
description: Empty body in response
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns a `not_found` error if the
shield information barrier segment restriction was not found.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Delete shield information barrier segment restriction by ID
tags:
- Shield information barrier segment restrictions
x-box-scopes:
- manage_managed_users
x-box-tag: shield_information_barrier_segment_restrictions
get:
description: |-
Retrieves a shield information barrier segment
restriction based on provided ID.
operationId: get_shield_information_barrier_segment_restrictions_id
parameters:
- description: The ID of the shield information barrier segment Restriction.
example: "4563"
in: path
name: shield_information_barrier_segment_restriction_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/ShieldInformationBarrierSegmentRestriction"
description: |-
Returns the shield information barrier segment
restriction object.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns a `not_found` error if the
shield information barrier segment
restriction was not found.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get shield information barrier segment restriction by ID
tags:
- Shield information barrier segment restrictions
x-box-scopes:
- manage_managed_users
x-box-tag: shield_information_barrier_segment_restrictions
/shield_information_barrier_segments:
get:
description: |-
Retrieves a list of shield information barrier segment objects
for the specified Information Barrier ID.
operationId: get_shield_information_barrier_segments
parameters:
- description: The ID of the shield information barrier.
example: "1910967"
in: query
name: shield_information_barrier_id
required: true
schema:
type: string
- description: |-
Defines the position marker at which to begin returning results. This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
in: query
name: marker
required: false
schema:
type: string
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
responses:
"200":
content:
application/json:
schema:
properties:
entries:
items:
$ref: "#/components/schemas/ShieldInformationBarrierSegment"
type: array
limit:
description: |-
The limit that was used for these entries.
This will be the same as the
`limit` query parameter unless
that value exceeded the maximum value
allowed. The maximum value varies by API.
example: 1000
format: int64
type: integer
next_marker:
description: The marker for the start of the next page of results.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
type: string
type: object
description: Returns a paginated list of shield information barrier segment objects.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns a `not_found` error if the shield information
Barrier of given ID was not found.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List shield information barrier segments
tags:
- Shield information barrier segments
x-box-scopes:
- manage_managed_users
x-box-tag: shield_information_barrier_segments
post:
description: Creates a shield information barrier segment.
operationId: post_shield_information_barrier_segments
requestBody:
content:
application/json:
schema:
properties:
description:
description: Description of the shield information barrier segment
example: |-
'Corporate division that engages in
advisory_based financial
transactions on behalf of individuals,
corporations, and governments.'
type: string
name:
description: Name of the shield information barrier segment
example: Investment Banking
type: string
shield_information_barrier:
$ref: "#/components/schemas/ShieldInformationBarrier--Base"
required:
- shield_information_barrier
- name
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/ShieldInformationBarrierSegment"
description: Returns a new shield information barrier segment object.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if the shield information barrier
was not found.
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if there exists an shield information
barrier segment with same name.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Create shield information barrier segment
tags:
- Shield information barrier segments
x-box-scopes:
- manage_managed_users
x-box-tag: shield_information_barrier_segments
"/shield_information_barrier_segments/{shield_information_barrier_segment_id}":
delete:
description: |-
Deletes the shield information barrier segment
based on provided ID.
operationId: delete_shield_information_barrier_segments_id
parameters:
- description: The ID of the shield information barrier segment.
example: "3423"
in: path
name: shield_information_barrier_segment_id
required: true
schema:
type: string
responses:
"204":
description: Empty body in response
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns a `not_found` error if the shield information
barrier segment with specified ID was not found.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Delete shield information barrier segment
tags:
- Shield information barrier segments
x-box-scopes:
- manage_managed_users
x-box-tag: shield_information_barrier_segments
get:
description: Retrieves shield information barrier segment based on provided ID..
operationId: get_shield_information_barrier_segments_id
parameters:
- description: The ID of the shield information barrier segment.
example: "3423"
in: path
name: shield_information_barrier_segment_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/ShieldInformationBarrierSegment"
description: Returns the shield information barrier segment object.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns a `not_found` error if the
shield information barrier segment was not found.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get shield information barrier segment with specified ID
tags:
- Shield information barrier segments
x-box-scopes:
- manage_managed_users
x-box-tag: shield_information_barrier_segments
put:
description: Updates the shield information barrier segment based on provided ID..
operationId: put_shield_information_barrier_segments_id
parameters:
- description: The ID of the shield information barrier segment.
example: "3423"
in: path
name: shield_information_barrier_segment_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
description: |-
An object containing update(s) to be made on the Shield
Information Barrier Segment. Possible properties include
'name' and 'description', the value in object is the update.
properties:
description:
description: |-
The updated description for
the shield information barrier segment.
example: |-
'Corporate division that engages in advisory_based
financial transactions on behalf of individuals,
corporations, and governments.'
nullable: true
type: string
name:
description: The updated name for the shield information barrier segment.
example: Investment Banking
pattern: \S+
type: string
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/ShieldInformationBarrierSegment"
description: Returns the updated shield information barrier segment object.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns a `not_found` error if the shield information
Barrier Segment was not found.
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if there exists a shield information
Barrier Segment with the same name.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Update shield information barrier segment with specified ID
tags:
- Shield information barrier segments
x-box-scopes:
- manage_managed_users
x-box-tag: shield_information_barrier_segments
/shield_information_barriers:
get:
description: |-
Retrieves a list of shield information barrier objects
for the enterprise of JWT.
operationId: get_shield_information_barriers
parameters:
- description: |-
Defines the position marker at which to begin returning results. This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
in: query
name: marker
required: false
schema:
type: string
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
responses:
"200":
content:
application/json:
schema:
properties:
entries:
items:
$ref: "#/components/schemas/ShieldInformationBarrier"
type: array
limit:
description: |-
The limit that was used for these entries.
This will be the same as the
`limit` query parameter unless that
value exceeded the maximum value
allowed. The maximum value varies by API.
example: 1000
format: int64
type: integer
next_marker:
description: The marker for the start of the next page of results.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
type: string
type: object
description: |-
Returns a paginated list of
shield information barrier objects,
empty list if currently no barrier.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns a `not_found` error if could not find an enterprise using JWT.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List shield information barriers
tags:
- Shield information barriers
x-box-scopes:
- manage_managed_users
x-box-tag: shield_information_barriers
post:
description: |-
Creates a shield information barrier to
separate individuals/groups within the same
firm and prevents confidential information passing between them.
operationId: post_shield_information_barriers
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/ShieldInformationBarrier"
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/ShieldInformationBarrier"
description: Returns a new shield information barrier object.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if the enterprise was not found.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Create shield information barrier
tags:
- Shield information barriers
x-box-scopes:
- manage_managed_users
x-box-tag: shield_information_barriers
/shield_information_barriers/change_status:
post:
description: Change status of shield information barrier with the specified ID.
operationId: post_shield_information_barriers_change_status
requestBody:
content:
application/json:
schema:
properties:
id:
description: The ID of the shield information barrier.
example: "1910967"
type: string
status:
description: The desired status for the shield information barrier.
enum:
- pending
- disabled
example: pending
type: string
required:
- id
- status
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/ShieldInformationBarrier"
description: Returns the updated shield information barrier object.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns a `not_found` error if the
shield information barrier was not found.
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if there exists Conflicts
with existing information barriers.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Add changed status of shield information barrier with specified ID
tags:
- Shield information barriers
x-box-scopes:
- manage_managed_users
x-box-tag: shield_information_barriers
"/shield_information_barriers/{shield_information_barrier_id}":
get:
description: Get shield information barrier based on provided ID..
operationId: get_shield_information_barriers_id
parameters:
- description: The ID of the shield information barrier.
example: "1910967"
in: path
name: shield_information_barrier_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/ShieldInformationBarrier"
description: Returns the shield information barrier object.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns a `not_found` error if
the shield information barrier was not found.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get shield information barrier with specified ID
tags:
- Shield information barriers
x-box-scopes:
- manage_managed_users
x-box-tag: shield_information_barriers
/sign_requests:
get:
description: |-
Gets sign requests created by a user. If the `sign_files` and/or
`parent_folder` are deleted, the sign request will not return in the list.
operationId: get_sign_requests
parameters:
- description: |-
Defines the position marker at which to begin returning results. This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
in: query
name: marker
required: false
schema:
type: string
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/SignRequests"
description: Returns a collection of sign requests
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List sign requests
tags:
- Box Sign
x-box-tag: sign_requests
post:
description: |-
Creates a sign request. This involves preparing a document for signing and
sending the sign request to signers.
operationId: post_sign_requests
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/SignRequestCreateRequest"
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/SignRequest"
description: Returns a Sign Request object.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Create sign request
tags:
- Box Sign
x-box-tag: sign_requests
"/sign_requests/{sign_request_id}":
get:
description: Gets a sign request by ID.
operationId: get_sign_requests_id
parameters:
- description: The ID of the sign request
example: "33243242"
in: path
name: sign_request_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/SignRequest"
description: Returns a sign request
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error when the sign request cannot be found, the user does
not have access to the sign request, or `sign_files` and/or
`parent_folder` is deleted.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get sign request by ID
tags:
- Box Sign
x-box-tag: sign_requests
"/sign_requests/{sign_request_id}/cancel":
post:
description: Cancels a sign request.
operationId: post_sign_requests_id_cancel
parameters:
- description: The ID of the sign request
example: "33243242"
in: path
name: sign_request_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/SignRequest"
description: Returns a Sign Request object.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error when the sign request cannot be found or the user does
not have access to the sign request.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Cancel sign request
tags:
- Box Sign
x-box-tag: sign_requests
"/sign_requests/{sign_request_id}/resend":
post:
description: Resends a sign request email to all outstanding signers.
operationId: post_sign_requests_id_resend
parameters:
- description: The ID of the sign request
example: "33243242"
in: path
name: sign_request_id
required: true
schema:
type: string
responses:
"202":
description: |-
Returns an empty response when the API call was successful.
The email notifications will be sent asynchronously.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error when the sign request cannot be found or the user does
not have access to the sign request.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Resend sign request
tags:
- Box Sign
x-box-tag: sign_requests
"/skill_invocations/{skill_id}":
put:
description: |-
An alternative method that can be used to overwrite and update all Box Skill
metadata cards on a file.
operationId: put_skill_invocations_id
parameters:
- description: The ID of the skill to apply this metadata for.
example: "33243242"
in: path
name: skill_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
file:
description: The file to assign the cards to.
properties:
id:
description: The ID of the file
example: "3243244"
type: string
type:
description: "`file`"
enum:
- file
example: file
type: string
type: object
file_version:
description: The optional file version to assign the cards to.
properties:
id:
description: The ID of the file version
example: "731381601045"
type: string
type:
description: "`file_version`"
enum:
- file_version
example: file_version
type: string
type: object
metadata:
description: |-
The metadata to set for this skill. This is a list of
Box Skills cards. These cards will overwrite any existing Box
skill cards on the file.
properties:
cards:
description: A list of Box Skill cards to apply to this file.
items:
oneOf:
- $ref: "#/components/schemas/KeywordSkillCard"
- $ref: "#/components/schemas/TimelineSkillCard"
- $ref: "#/components/schemas/TranscriptSkillCard"
- $ref: "#/components/schemas/StatusSkillCard"
type: array
type: object
status:
description: Defines the status of this invocation. Set this to `success` when setting Skill cards.
enum:
- invoked
- processing
- success
- transient_failure
- permanent_failure
example: success
type: string
usage:
description: |-
A descriptor that defines what items are affected by this call.
Set this to the default values when setting a card to a `success`
state, and leave it out in most other situations.
properties:
unit:
description: "`file`"
example: file
type: string
value:
description: "`1`"
example: 1
type: number
type: object
required:
- status
- metadata
- file
type: object
responses:
"200":
description: Returns an empty response when the card has been successfully updated.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error when the request body is not valid.
* `schema_validation_failed` - The request body contains a value for a 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.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Update all Box Skill cards on file
tags:
- Skills
x-box-tag: skills
/storage_policies:
get:
description: Fetches all the storage policies in the enterprise.
operationId: get_storage_policies
parameters:
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
- description: |-
Defines the position marker at which to begin returning results. This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
in: query
name: marker
required: false
schema:
type: string
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/StoragePolicies"
description: Returns a collection of storage policies.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List storage policies
tags:
- Storage policies
x-box-tag: storage_policies
"/storage_policies/{storage_policy_id}":
get:
description: Fetches a specific storage policy.
operationId: get_storage_policies_id
parameters:
- description: The ID of the storage policy.
example: "34342"
in: path
name: storage_policy_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/StoragePolicy"
description: Returns a storage policy object.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get storage policy
tags:
- Storage policies
x-box-tag: storage_policies
/storage_policy_assignments:
get:
description: Fetches all the storage policy assignment for an enterprise or user.
operationId: get_storage_policy_assignments
parameters:
- description: |-
Defines the position marker at which to begin returning results. This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
in: query
name: marker
required: false
schema:
type: string
- description: The target type to return assignments for
example: user
in: query
name: resolved_for_type
required: true
schema:
enum:
- user
- enterprise
type: string
- description: The ID of the user or enterprise to return assignments for
example: "984322"
in: query
name: resolved_for_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/StoragePolicyAssignments"
description: |-
Returns a collection of storage policies for
the enterprise or user.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List storage policy assignments
tags:
- Storage policy assignments
x-box-tag: storage_policy_assignments
post:
description: Creates a storage policy assignment for an enterprise or user.
operationId: post_storage_policy_assignments
requestBody:
content:
application/json:
schema:
properties:
assigned_to:
description: |-
The user or enterprise to assign the storage
policy to.
properties:
id:
description: The ID of the user or enterprise
example: "9987987"
type: string
type:
description: The type to assign the policy to.
enum:
- user
- enterprise
example: user
type: string
required:
- type
- id
type: object
storage_policy:
description: |-
The storage policy to assign to the user or
enterprise
properties:
id:
description: The ID of the storage policy to assign.
example: "1434325"
type: string
type:
description: The type to assign.
enum:
- storage_policy
example: storage_policy
type: string
required:
- type
- id
type: object
required:
- storage_policy
- assigned_to
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/StoragePolicyAssignment"
description: Returns the new storage policy assignment created.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Assign storage policy
tags:
- Storage policy assignments
x-box-tag: storage_policy_assignments
"/storage_policy_assignments/{storage_policy_assignment_id}":
delete:
description: |-
Delete a storage policy assignment.
Deleting a storage policy assignment on a user
will have the user inherit the enterprise's default
storage policy.
There is a rate limit for calling this endpoint of only
twice per user in a 24 hour time frame.
operationId: delete_storage_policy_assignments_id
parameters:
- description: The ID of the storage policy assignment.
example: "932483"
in: path
name: storage_policy_assignment_id
required: true
schema:
type: string
responses:
"204":
description: |-
Returns an empty response when the storage policy
assignment is successfully deleted.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Unassign storage policy
tags:
- Storage policy assignments
x-box-tag: storage_policy_assignments
get:
description: Fetches a specific storage policy assignment.
operationId: get_storage_policy_assignments_id
parameters:
- description: The ID of the storage policy assignment.
example: "932483"
in: path
name: storage_policy_assignment_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/StoragePolicyAssignment"
description: Returns a storage policy assignment object.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get storage policy assignment
tags:
- Storage policy assignments
x-box-tag: storage_policy_assignments
put:
description: Updates a specific storage policy assignment.
operationId: put_storage_policy_assignments_id
parameters:
- description: The ID of the storage policy assignment.
example: "932483"
in: path
name: storage_policy_assignment_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
storage_policy:
description: |-
The storage policy to assign to the user or
enterprise
properties:
id:
description: The ID of the storage policy to assign.
example: "1434325"
type: string
type:
description: The type to assign.
enum:
- storage_policy
example: storage_policy
type: string
required:
- type
- id
type: object
required:
- storage_policy
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/StoragePolicyAssignment"
description: Returns an updated storage policy assignment object.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Update storage policy assignment
tags:
- Storage policy assignments
x-box-tag: storage_policy_assignments
/task_assignments:
post:
description: |-
Assigns a task to a user.
A task can be assigned to more than one user by creating multiple
assignments.
operationId: post_task_assignments
requestBody:
content:
application/json:
schema:
properties:
assign_to:
description: The user to assign the task to.
properties:
id:
description: |-
The ID of the user to assign to the
task.
To specify a user by their email
address use the `login` parameter.
example: "3242343"
type: string
login:
description: |-
The email address of the user to assign to the task.
To specify a user by their user ID please use the `id` parameter.
example: john@example.com
type: string
type: object
task:
description: The task to assign to a user.
properties:
id:
description: The ID of the task
example: "11446498"
type: string
type:
description: The type of the item to assign.
enum:
- task
example: task
type: string
required:
- id
- type
type: object
required:
- task
- assign_to
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/TaskAssignment"
description: Returns a new task assignment object.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error when the task cannot be found.
"500":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Assign task
tags:
- Task assignments
x-box-sanitized: true
x-box-tag: task_assignments
"/task_assignments/{task_assignment_id}":
delete:
description: Deletes a specific task assignment.
operationId: delete_task_assignments_id
parameters:
- description: The ID of the task assignment.
example: "12345"
in: path
name: task_assignment_id
required: true
schema:
type: string
responses:
"204":
description: |-
Returns an empty response when the task
assignment was successfully deleted.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if the task assignment for the given ID does not exist
or is inaccessible to your account.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Unassign task
tags:
- Task assignments
x-box-sanitized: true
x-box-tag: task_assignments
get:
description: Retrieves information about a task assignment.
operationId: get_task_assignments_id
parameters:
- description: The ID of the task assignment.
example: "12345"
in: path
name: task_assignment_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/TaskAssignment"
description: |-
Returns a task assignment, specifying who the task has been assigned to
and by whom.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get task assignment
tags:
- Task assignments
x-box-sanitized: true
x-box-tag: task_assignments
put:
description: |-
Updates a task assignment. This endpoint can be
used to update the state of a task assigned to a user.
operationId: put_task_assignments_id
parameters:
- description: The ID of the task assignment.
example: "12345"
in: path
name: task_assignment_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
message:
description: An optional message by the assignee that can be added to the task.
example: Looks good to me
type: string
resolution_state:
description: |-
The state of the task assigned to the user.
* For a task with an `action` value of `complete` this can be
`incomplete` or `completed`.
* For a task with an `action` of `review` this can be
`incomplete`, `approved`, or `rejected`.
enum:
- completed
- incomplete
- approved
- rejected
example: completed
type: string
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/TaskAssignment"
description: Returns the updated task assignment object.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if a resolution state is incompatible with the action
type of the task.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Update task assignment
tags:
- Task assignments
x-box-sanitized: true
x-box-tag: task_assignments
/tasks:
post:
description: |-
Creates a single task on a file. This task is not assigned to any user and
will need to be assigned separately.
operationId: post_tasks
requestBody:
content:
application/json:
schema:
properties:
action:
default: review
description: |-
The action the task assignee will be prompted to do. Must be
* `review` defines an approval task that can be approved or
rejected
* `complete` defines a general task which can be completed
enum:
- review
- complete
example: review
type: string
completion_rule:
default: all_assignees
description: |-
Defines which assignees need to complete this task before the task
is considered completed.
* `all_assignees` (default) requires all assignees to review or
approve the the task in order for it to be considered completed.
* `any_assignee` accepts any one assignee to review or
approve the the task in order for it to be considered completed.
enum:
- all_assignees
- any_assignee
example: all_assignees
type: string
due_at:
description: |-
Defines when the task is due. Defaults to `null` if not
provided.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
item:
description: The file to attach the task to.
properties:
id:
description: The ID of the file
example: "11446498"
type: string
type:
description: "`file`"
enum:
- file
example: file
type: string
required:
- id
- type
type: object
message:
default: ""
description: An optional message to include with the task.
example: Please review
type: string
required:
- item
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/Task"
description: Returns the newly created task.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error when the user does not have the permission to create a
task on the file.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error when the file could not be found or the user does not
have access to the file.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Create task
tags:
- Tasks
x-box-sanitized: true
x-box-tag: tasks
"/tasks/{task_id}":
delete:
description: Removes a task from a file.
operationId: delete_tasks_id
parameters:
- description: The ID of the task.
example: "12345"
in: path
name: task_id
required: true
schema:
type: string
responses:
"204":
description: Returns an empty response when the task was successfully deleted.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Remove task
tags:
- Tasks
x-box-sanitized: true
x-box-tag: tasks
get:
description: Retrieves information about a specific task.
operationId: get_tasks_id
parameters:
- description: The ID of the task.
example: "12345"
in: path
name: task_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Task"
description: Returns a task object.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get task
tags:
- Tasks
x-box-sanitized: true
x-box-tag: tasks
put:
description: |-
Updates a task. This can be used to update a task's configuration, or to
update its completion state.
operationId: put_tasks_id
parameters:
- description: The ID of the task.
example: "12345"
in: path
name: task_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
action:
description: |-
The action the task assignee will be prompted to do. Must be
* `review` defines an approval task that can be approved or
rejected
* `complete` defines a general task which can be completed
enum:
- review
- complete
example: review
type: string
completion_rule:
description: |-
Defines which assignees need to complete this task before the task
is considered completed.
* `all_assignees` (default) requires all assignees to review or
approve the the task in order for it to be considered completed.
* `any_assignee` accepts any one assignee to review or
approve the the task in order for it to be considered completed.
enum:
- all_assignees
- any_assignee
example: all_assignees
type: string
due_at:
description: When the task is due at.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
message:
description: The message included with the task.
example: Please review
type: string
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Task"
description: Returns the updated task object
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error when the user does not have the permission to update a
task on the file.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error when the file could not be found or the user does not
have access to the file.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Update task
tags:
- Tasks
x-box-sanitized: true
x-box-tag: tasks
"/tasks/{task_id}/assignments":
get:
description: Lists all of the assignments for a given task.
operationId: get_tasks_id_assignments
parameters:
- description: The ID of the task.
example: "12345"
in: path
name: task_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/TaskAssignments"
description: |-
Returns a collection of task assignment defining what task on
a file has been assigned to which users and by who.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"500":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if the task assignment ID was omitted in
the request.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List task assignments
tags:
- Task assignments
x-box-sanitized: true
x-box-tag: task_assignments
/terms_of_service_user_statuses:
get:
description: |-
Retrieves an overview of users and their status for a
terms of service, including Whether they have accepted
the terms and when.
operationId: get_terms_of_service_user_statuses
parameters:
- description: The ID of the terms of service.
example: "324234"
in: query
name: tos_id
required: true
schema:
type: string
- description: Limits results to the given user ID.
example: "123334"
in: query
name: user_id
required: false
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/TermsOfServiceUserStatuses"
description: Returns a list of terms of service statuses.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List terms of service user statuses
tags:
- Terms of service user statuses
x-box-tag: terms_of_service_user_statuses
post:
description: Sets the status for a terms of service for a user.
operationId: post_terms_of_service_user_statuses
requestBody:
content:
application/json:
schema:
properties:
is_accepted:
description: Whether the user has accepted the terms.
example: true
type: boolean
tos:
description: The terms of service to set the status for.
properties:
id:
description: The ID of terms of service
example: "1232132"
type: string
type:
description: The type of object.
enum:
- terms_of_service
example: terms_of_service
type: string
required:
- id
- type
type: object
user:
description: The user to set the status for.
properties:
id:
description: The ID of user
example: "3423423"
type: string
type:
description: The type of object.
enum:
- user
example: user
type: string
required:
- id
- type
type: object
required:
- tos
- user
- is_accepted
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/TermsOfServiceUserStatus"
description: Returns a terms of service status object.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Create terms of service status for new user
tags:
- Terms of service user statuses
x-box-tag: terms_of_service_user_statuses
"/terms_of_service_user_statuses/{terms_of_service_user_status_id}":
put:
description: Updates the status for a terms of service for a user.
operationId: put_terms_of_service_user_statuses_id
parameters:
- description: The ID of the terms of service status.
example: "324234"
in: path
name: terms_of_service_user_status_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
is_accepted:
description: Whether the user has accepted the terms.
example: true
type: boolean
required:
- is_accepted
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/TermsOfServiceUserStatus"
description: Returns the updated terms of service status object.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Update terms of service status for existing user
tags:
- Terms of service user statuses
x-box-tag: terms_of_service_user_statuses
/terms_of_services:
get:
description: |-
Returns the current terms of service text and settings
for the enterprise.
operationId: get_terms_of_services
parameters:
- description: Limits the results to the terms of service of the given type.
example: managed
in: query
name: tos_type
required: false
schema:
enum:
- external
- managed
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/TermsOfServices"
description: |-
Returns a collection of terms of service text and settings for the
enterprise.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List terms of services
tags:
- Terms of service
x-box-tag: terms_of_services
post:
description: |-
Creates a terms of service for a given enterprise
and type of user.
operationId: post_terms_of_services
requestBody:
content:
application/json:
schema:
properties:
status:
description: Whether this terms of service is active.
enum:
- enabled
- disabled
example: enabled
type: string
text:
description: |-
The terms of service text to display to users.
The text can be set to empty if the `status` is set to `disabled`.
example: By collaborating on this file you are accepting...
type: string
tos_type:
description: |-
The type of user to set the terms of
service for.
enum:
- external
- managed
example: managed
type: string
required:
- status
- text
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Task"
description: Returns a new task object
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Create terms of service
tags:
- Terms of service
x-box-tag: terms_of_services
"/terms_of_services/{terms_of_service_id}":
get:
description: Fetches a specific terms of service.
operationId: get_terms_of_services_id
parameters:
- description: The ID of the terms of service.
example: "324234"
in: path
name: terms_of_service_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/TermsOfService"
description: Returns a terms of service object.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get terms of service
tags:
- Terms of service
x-box-tag: terms_of_services
put:
description: Updates a specific terms of service.
operationId: put_terms_of_services_id
parameters:
- description: The ID of the terms of service.
example: "324234"
in: path
name: terms_of_service_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
status:
description: Whether this terms of service is active.
enum:
- enabled
- disabled
example: enabled
type: string
text:
description: |-
The terms of service text to display to users.
The text can be set to empty if the `status` is set to `disabled`.
example: By collaborating on this file you are accepting...
type: string
required:
- status
- text
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/TermsOfService"
description: Returns an updated terms of service object.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Update terms of service
tags:
- Terms of service
x-box-tag: terms_of_services
/users:
get:
description: |-
Returns a list of all users for the Enterprise along with their `user_id`,
`public_name`, and `login`.
The application and the authenticated user need to
have the permission to look up users in the entire
enterprise.
operationId: get_users
parameters:
- description: |-
Limits the results to only users who's `name` or
`login` start with the search term.
For externally managed users, the search term needs
to completely match the in order to find the user, and
it will only return one user at a time.
example: john
in: query
name: filter_term
required: false
schema:
type: string
- description: |-
Limits the results to the kind of user specified.
* `all` returns every kind of user for whom the
`login` or `name` partially matches the
`filter_term`. It will only return an external user
if the login matches the `filter_term` completely,
and in that case it will only return that user.
* `managed` returns all managed and app users for whom
the `login` or `name` partially matches the
`filter_term`.
* `external` returns all external users for whom the
`login` matches the `filter_term` exactly.
example: managed
in: query
name: user_type
required: false
schema:
enum:
- all
- managed
- external
type: string
- description: |-
Limits the results to app users with the given
`external_app_user_id` value.
When creating an app user, an
`external_app_user_id` value can be set. This value can
then be used in this endpoint to find any users that
match that `external_app_user_id` value.
example: my-user-1234
in: query
name: external_app_user_id
required: false
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
- description: |-
The offset of the item at which to begin the response.
Queries with offset parameter value
exceeding 10000 will be rejected
with a 400 response.
example: 1000
in: query
name: offset
required: false
schema:
default: 0
format: int64
type: integer
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
- description: |-
Specifies whether to use marker-based pagination instead of
offset-based pagination. Only one pagination method can
be used at a time.
By setting this value to true, the API will return a `marker` field
that can be passed as a parameter to this endpoint to get the next
page of the response.
example: true
in: query
name: usemarker
required: false
schema:
type: boolean
- description: |-
Defines the position marker at which to begin returning results. This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
in: query
name: marker
required: false
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Users"
description: Returns all of the users in the enterprise.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List enterprise users
tags:
- Users
x-box-tag: users
post:
description: |-
Creates a new managed user in an enterprise. This endpoint
is only available to users and applications with the right
admin permissions.
operationId: post_users
parameters:
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
requestBody:
content:
application/json:
schema:
properties:
address:
description: The user’s address
example: 900 Jefferson Ave, Redwood City, CA 94063
maxLength: 255
type: string
can_see_managed_users:
description: |-
Whether the user can see other enterprise users in their
contact list
example: true
type: boolean
external_app_user_id:
description: |-
An external identifier for an app user, which can be used to look
up the user. This can be used to tie user IDs from external
identity providers to Box users.
example: my-user-1234
type: string
is_exempt_from_device_limits:
description: Whether to exempt the user from enterprise device limits
example: true
type: boolean
is_exempt_from_login_verification:
description: Whether the user must use two-factor authentication
example: true
type: boolean
is_external_collab_restricted:
description: |-
Whether the user is allowed to collaborate with users outside
their enterprise
example: true
type: boolean
is_platform_access_only:
description: Specifies that the user is an app user.
example: true
type: boolean
is_sync_enabled:
description: Whether the user can use Box Sync
example: true
type: boolean
job_title:
description: The user’s job title
example: CEO
maxLength: 100
type: string
language:
description: |-
The language of the user, formatted in modified version of the
[ISO 639-1](/guides/api-calls/language-codes) format.
example: en
type: string
login:
description: |-
The email address the user uses to log in
Required, unless `is_platform_access_only`
is set to `true`.
example: boss@box.com
type: string
name:
description: The name of the user
example: Aaron Levie
maxLength: 50
type: string
phone:
description: The user’s phone number
example: "6509241374"
maxLength: 100
type: string
role:
description: The user’s enterprise role
enum:
- coadmin
- user
example: user
type: string
space_amount:
description: |-
The user’s total available space in bytes. Set this to `-1` to
indicate unlimited storage.
example: 11345156112
format: int64
type: integer
status:
description: The user's account status
enum:
- active
- inactive
- cannot_delete_edit
- cannot_delete_edit_upload
example: active
type: string
timezone:
description: The user's timezone
example: Africa/Bujumbura
format: timezone
type: string
tracking_codes:
description: |-
Tracking codes allow an admin to generate reports from the
admin console and assign an attribute to a specific group
of users. This setting must be enabled for an enterprise before it
can be used.
items:
$ref: "#/components/schemas/TrackingCode"
type: array
required:
- name
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/User"
description: Returns a user object for the newly created user.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Create user
tags:
- Users
x-box-tag: users
/users/me:
get:
description: |-
Retrieves information about the user who is currently authenticated.
In the case of a client-side authenticated OAuth 2.0 application
this will be the user who authorized the app.
In the case of a JWT, server-side authenticated application
this will be the service account that belongs to the application
by default.
Use the `As-User` header to change who this API call is made on behalf of.
operationId: get_users_me
parameters:
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/User--Full"
description: Returns a single user object.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get current user
tags:
- Users
x-box-tag: users
/users/terminate_sessions:
post:
description: |-
Validates the roles and permissions of the user,
and creates asynchronous jobs
to terminate the user's sessions.
Returns the status for the POST request.
operationId: post_users_terminate_sessions
requestBody:
content:
application/json:
schema:
properties:
user_ids:
description: A list of user IDs
example:
- "123456"
- "456789"
items:
type: string
type: array
user_logins:
description: A list of user logins
example:
- user@sample.com
- user2@sample.com
items:
type: string
type: array
required:
- user_ids
- user_logins
type: object
responses:
"202":
content:
application/json:
schema:
$ref: "#/components/schemas/SessionTerminationMessage"
description: Returns a message about the request status.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if there are insufficient permissions.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if the resource could not be found.
"429":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if the rate limit is exceeded.
"500":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if there is an internal server issue.
"503":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if the request timed out.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Create jobs to terminate users session
tags:
- Users
x-box-tag: session_termination
"/users/{user_id}":
delete:
description: |-
Deletes a user. By default this will fail if the user
still owns any content. Move their owned content first
before proceeding, or use the `force` field to delete
the user and their files.
operationId: delete_users_id
parameters:
- description: The ID of the user.
example: "12345"
in: path
name: user_id
required: true
schema:
type: string
- description: |-
Whether the user will receive email notification of
the deletion
example: true
in: query
name: notify
schema:
type: boolean
- description: |-
Whether the user should be deleted even if this user
still own files
example: true
in: query
name: force
schema:
type: boolean
responses:
"204":
description: Removes the user and returns an empty response.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Delete user
tags:
- Users
x-box-tag: users
get:
description: |-
Retrieves information about a user in the enterprise.
The application and the authenticated user need to
have the permission to look up users in the entire
enterprise.
This endpoint also returns a limited set of information
for external users who are collaborated on content
owned by the enterprise for authenticated users with the
right scopes. In this case, disallowed fields will return
null instead.
operationId: get_users_id
parameters:
- description: The ID of the user.
example: "12345"
in: path
name: user_id
required: true
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/User--Full"
description: |-
Returns a single user object.
Not all available fields are returned by default. Use the
[fields](#param-fields) query parameter to explicitly request
any specific fields using the [fields](#get-users-id--request--fields)
parameter.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get user
tags:
- Users
x-box-tag: users
put:
description: |-
Updates a managed or app user in an enterprise. This endpoint
is only available to users and applications with the right
admin permissions.
operationId: put_users_id
parameters:
- description: The ID of the user.
example: "12345"
in: path
name: user_id
required: true
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
requestBody:
content:
application/json:
schema:
properties:
address:
description: The user’s address
example: 900 Jefferson Ave, Redwood City, CA 94063
maxLength: 255
type: string
can_see_managed_users:
description: |-
Whether the user can see other enterprise users in their
contact list
example: true
type: boolean
enterprise:
description: |-
Set this to `null` to roll the user out of the enterprise
and make them a free user
example: null
nullable: true
type: string
external_app_user_id:
description: |-
An external identifier for an app user, which can be used to look
up the user. This can be used to tie user IDs from external
identity providers to Box users.
Note: In order to update this field, you need to request a token
using the application that created the app user.
example: my-user-1234
type: string
is_exempt_from_device_limits:
description: Whether to exempt the user from enterprise device limits
example: true
type: boolean
is_exempt_from_login_verification:
description: Whether the user must use two-factor authentication
example: true
type: boolean
is_external_collab_restricted:
description: |-
Whether the user is allowed to collaborate with users outside
their enterprise
example: true
type: boolean
is_password_reset_required:
description: Whether the user is required to reset their password
example: true
type: boolean
is_sync_enabled:
description: Whether the user can use Box Sync
example: true
type: boolean
job_title:
description: The user’s job title
example: CEO
maxLength: 100
type: string
language:
description: |-
The language of the user, formatted in modified version of the
[ISO 639-1](/guides/api-calls/language-codes) format.
example: en
type: string
login:
description: |-
The email address the user uses to log in
Note: If the target user's email is not confirmed, then the
primary login address cannot be changed.
example: somename@box.com
type: string
name:
description: The name of the user
example: Aaron Levie
maxLength: 50
type: string
notification_email:
description: |-
An alternate notification email address to which email
notifications are sent. When it's confirmed, this will be
the email address to which notifications are sent instead of
to the primary email address.
Set this value to `null` to remove the notification email.
nullable: true
properties:
email:
description: The email address to send the notifications to.
example: notifications@example.com
type: string
type: object
notify:
description: |-
Whether the user should receive an email when they
are rolled out of an enterprise
example: true
type: boolean
phone:
description: The user’s phone number
example: "6509241374"
maxLength: 100
type: string
role:
description: The user’s enterprise role
enum:
- coadmin
- user
example: user
type: string
space_amount:
description: |-
The user’s total available space in bytes. Set this to `-1` to
indicate unlimited storage.
example: 11345156112
format: int64
type: integer
status:
description: The user's account status
enum:
- active
- inactive
- cannot_delete_edit
- cannot_delete_edit_upload
example: active
type: string
timezone:
description: The user's timezone
example: Africa/Bujumbura
format: timezone
type: string
tracking_codes:
description: |-
Tracking codes allow an admin to generate reports from the
admin console and assign an attribute to a specific group
of users. This setting must be enabled for an enterprise before it
can be used.
items:
$ref: "#/components/schemas/TrackingCode"
type: array
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/User--Full"
description: Returns the updated user object.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Update user
tags:
- Users
x-box-enable-explorer: true
x-box-tag: users
"/users/{user_id}/avatar":
delete:
description: |-
Removes an existing user avatar.
You cannot reverse this operation.
operationId: delete_users_id_avatar
parameters:
- description: The ID of the user.
example: "12345"
in: path
name: user_id
required: true
schema:
type: string
responses:
"204":
description: "* `no_content`: Removes the avatar and returns an empty response."
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
* `forbidden`: Returned if the user does not have necessary permissions
or is not activated.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
* `not_found`: Returned if the user or user avatar does not exist
or cannot be found.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Delete user avatar
tags:
- User avatars
x-box-tag: avatars
get:
description: Retrieves an image of a the user's avatar.
operationId: get_users_id_avatar
parameters:
- description: The ID of the user.
example: "12345"
in: path
name: user_id
required: true
schema:
type: string
responses:
"200":
content:
image/jpg:
schema:
description: The avatar
format: binary
type: string
description: |-
When an avatar can be found for the user the
image data will be returned in the body of the
response.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get user avatar
tags:
- User avatars
x-box-tag: avatars
post:
description: Adds or updates a user avatar.
operationId: post_users_id_avatar
parameters:
- description: The ID of the user.
example: "12345"
in: path
name: user_id
required: true
schema:
type: string
requestBody:
content:
multipart/form-data:
schema:
properties:
pic:
description: |-
The image file to be uploaded to Box.
Accepted file extensions are `.jpg` or `.png`.
The maximum file size is 1MB.
format: binary
type: string
required:
- pic
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/UserAvatar"
description: |-
* `ok`: Returns the `pic_urls` object with URLs to existing
user avatars that were updated.
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/UserAvatar"
description: |-
* `created`: Returns the `pic_urls` object with URLS to user avatars
uploaded to Box with the request.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
* `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`.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
* `forbidden`: Returns an error if the user does not have permissions
necessary to upload an avatar or is not activated.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
* `not_found`: Returns an error if the user
does not exist or cannot be found.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Add or update user avatar
tags:
- User avatars
x-box-tag: avatars
"/users/{user_id}/email_aliases":
get:
description: |-
Retrieves all email aliases for a user. The collection
does not include the primary login for the user.
operationId: get_users_id_email_aliases
parameters:
- description: The ID of the user.
example: "12345"
in: path
name: user_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/EmailAliases"
description: Returns a collection of email aliases.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List user's email aliases
tags:
- Email aliases
x-box-tag: email_aliases
post:
description: Adds a new email alias to a user account..
operationId: post_users_id_email_aliases
parameters:
- description: The ID of the user.
example: "12345"
in: path
name: user_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
email:
description: |-
The email address to add to the account as an alias.
Note: The domain of the email alias needs to be registered
to your enterprise.
See the [domain verification guide](
https://support.box.com/hc/en-us/articles/4408619650579-Domain-Verification
) for steps to add a new domain.
example: alias@example.com
type: string
required:
- email
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/EmailAlias"
description: Returns the newly created email alias object.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Create email alias
tags:
- Email aliases
x-box-tag: email_aliases
"/users/{user_id}/email_aliases/{email_alias_id}":
delete:
description: Removes an email alias from a user.
operationId: delete_users_id_email_aliases_id
parameters:
- description: The ID of the user.
example: "12345"
in: path
name: user_id
required: true
schema:
type: string
- description: The ID of the email alias.
example: "23432"
in: path
name: email_alias_id
required: true
schema:
type: string
responses:
"204":
description: Removes the alias and returns an empty response.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Remove email alias
tags:
- Email aliases
x-box-tag: email_aliases
"/users/{user_id}/folders/0":
put:
description: |-
Move all of the items (files, folders and workflows) owned by a user into
another user's account
Only the root folder (`0`) can be transferred.
Folders can only be moved across users by users with administrative
permissions.
All existing shared links and folder-level collaborations are transferred
during the operation. Please note that while collaborations at the individual
file-level are transferred during the operation, the collaborations are
deleted when the original user is deleted.
This call will be performed synchronously which might lead to a slow response
when the source user has a large number of items in all of its folders.
If the destination path has a metadata cascade policy attached to any of
the parent folders, a metadata cascade operation will be kicked off
asynchronously.
There is currently no way to check for when this operation is finished.
The destination folder's name will be in the format `{User}'s Files and
Folders`, where `{User}` is the display name of the user.
To make this API call your application will need to have the "Read and write
all files and folders stored in Box" scope enabled.
Please make sure the destination user has access to `Relay` or `Relay Lite`,
and has access to the files and folders involved in the workflows being
transferred.
Admins will receive an email when the operation is completed.
operationId: put_users_id_folders_0
parameters:
- description: The ID of the user.
example: "12345"
in: path
name: user_id
required: true
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
- description: |-
Determines if users should receive email notification
for the action performed.
example: true
in: query
name: notify
required: false
schema:
type: boolean
requestBody:
content:
application/json:
schema:
properties:
owned_by:
description: The user who the folder will be transferred to
properties:
id:
description: |-
The ID of the user who the folder will be
transferred to
example: "1232234"
type: string
required:
- id
type: object
required:
- owned_by
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Folder--Full"
description: |-
Returns the information for the newly created
destination folder.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Transfer owned folders
tags:
- Transfer folders
x-box-tag: transfer
"/users/{user_id}/memberships":
get:
description: |-
Retrieves all the groups for a user. Only members of this
group or users with admin-level permissions will be able to
use this API.
operationId: get_users_id_memberships
parameters:
- description: The ID of the user.
example: "12345"
in: path
name: user_id
required: true
schema:
type: string
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
- description: |-
The offset of the item at which to begin the response.
Queries with offset parameter value
exceeding 10000 will be rejected
with a 400 response.
example: 1000
in: query
name: offset
required: false
schema:
default: 0
format: int64
type: integer
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/GroupMemberships"
description: |-
Returns a collection of membership objects. If there are no
memberships, an empty collection will be returned.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List user's groups
tags:
- Group memberships
x-box-tag: memberships
/web_links:
post:
description: Creates a web link object within a folder.
operationId: post_web_links
requestBody:
content:
application/json:
schema:
properties:
description:
description: Description of the web link.
example: Cloud Content Management
type: string
name:
description: Name of the web link. Defaults to the URL if not set.
example: Box Website
type: string
parent:
description: The parent folder to create the web link within.
properties:
id:
description: The ID of parent folder
example: "0"
type: string
required:
- id
type: object
shared_link:
description: The settings for the shared link to update.
properties:
access:
description: |-
The level of access for the shared link. This can be
restricted to anyone with the link (`open`), only people
within the company (`company`) and only those who
have been invited to the folder (`collaborators`).
If not set, this field defaults to the access level specified
by the enterprise admin. To create a shared link with this
default setting pass the `shared_link` object with
no `access` field, for example `{ "shared_link": {} }`.
The `company` access level is only available to paid
accounts.
enum:
- open
- company
- collaborators
example: open
type: string
password:
description: |-
The password required to access the shared link. Set the
password to `null` to remove it.
A password can only be set when `access` is set to `open`.
example: do-not-use-this-password
type: string
unshared_at:
description: |-
The timestamp at which this shared link will
expire. This field can only be set by
users with paid accounts. The value must be greater than the
current date and time.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
vanity_name:
description: |-
Defines a custom vanity name to use in the shared link URL,
for example `https://app.box.com/v/my-shared-link`.
Custom URLs should not be used when sharing sensitive content
as vanity URLs are a lot easier to guess than regular shared
links.
example: my-shared-link
minLength: 12
type: string
type: object
url:
description: |-
The URL that this web link links to. Must start with
`"http://"` or `"https://"`.
example: https://box.com
type: string
required:
- parent
- url
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/WebLink"
description: Returns the newly created web link object.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Create web link
tags:
- Web links
x-box-tag: web_links
"/web_links/{web_link_id}":
delete:
description: Deletes a web link.
operationId: delete_web_links_id
parameters:
- description: The ID of the web link.
example: "12345"
in: path
name: web_link_id
required: true
schema:
type: string
responses:
"204":
description: |-
An empty response will be returned when the web link
was successfully deleted.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Remove web link
tags:
- Web links
x-box-tag: web_links
get:
description: Retrieve information about a web link.
operationId: get_web_links_id
parameters:
- description: The ID of the web link.
example: "12345"
in: path
name: web_link_id
required: true
schema:
type: string
- description: |-
The URL, and optional password, for the shared link of this item.
This header can be used to access items that have not been
explicitly shared with a user.
Use the format `shared_link=[link]` or if a password is required then
use `shared_link=[link]&shared_link_password=[password]`.
This header can be used on the file or folder shared, as well as on any files
or folders nested within the item.
example: shared_link=[link]&shared_link_password=[password]
in: header
name: boxapi
required: false
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/WebLink"
description: Returns the web link object.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get web link
tags:
- Web links
x-box-tag: web_links
post:
description: |-
Restores a web link that has been moved to the trash.
An optional new parent ID can be provided to restore the web link to in case
the original folder has been deleted.
operationId: post_web_links_id
parameters:
- description: The ID of the web link.
example: "12345"
in: path
name: web_link_id
required: true
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
requestBody:
content:
application/json:
schema:
properties:
name:
description: An optional new name for the web link.
example: Restored.docx
type: string
parent:
allOf:
- description: The parent for this item
properties:
id:
description: The ID of parent item
example: "123"
type: string
type: object
- description: |-
Specifies an optional ID of a folder to restore the web link
to when the original folder no longer exists.
Please be aware that this ID will only be used if the original
folder no longer exists. Use this ID to provide a fallback
location to restore the web link to if the original location
has been deleted.
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/TrashWebLinkRestored"
description: Returns a web link object when it has been restored.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if the web link is not in the trash.
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if there is an web link with the same name
in the folder the web link is being restored to.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Restore web link
tags:
- Trashed web links
x-box-tag: trashed_web_links
put:
description: Updates a web link object.
operationId: put_web_links_id
parameters:
- description: The ID of the web link.
example: "12345"
in: path
name: web_link_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
description:
description: A new description of the web link.
example: Cloud Content Management
type: string
name:
description: A new name for the web link. Defaults to the URL if not set.
example: Box Website
type: string
parent:
allOf:
- description: The parent for this item
properties:
id:
description: The ID of parent item
example: "123"
type: string
type: object
- description: |-
The new parent folder to put the web link in.
Use this to move the web link to a different folder.
shared_link:
description: The settings for the shared link to update.
properties:
access:
description: |-
The level of access for the shared link. This can be
restricted to anyone with the link (`open`), only people
within the company (`company`) and only those who
have been invited to the folder (`collaborators`).
If not set, this field defaults to the access level specified
by the enterprise admin. To create a shared link with this
default setting pass the `shared_link` object with
no `access` field, for example `{ "shared_link": {} }`.
The `company` access level is only available to paid
accounts.
enum:
- open
- company
- collaborators
example: open
type: string
password:
description: |-
The password required to access the shared link. Set the
password to `null` to remove it.
A password can only be set when `access` is set to `open`.
example: do-not-use-this-password
type: string
unshared_at:
description: |-
The timestamp at which this shared link will
expire. This field can only be set by
users with paid accounts. The value must be greater than the
current date and time.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
vanity_name:
description: |-
Defines a custom vanity name to use in the shared link URL,
for example `https://app.box.com/v/my-shared-link`.
Custom URLs should not be used when sharing sensitive content
as vanity URLs are a lot easier to guess than regular shared
links.
example: my-shared-link
minLength: 12
type: string
type: object
url:
description: |-
The new URL that the web link links to. Must start with
`"http://"` or `"https://"`.
example: https://box.com
type: string
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/WebLink"
description: Returns the updated web link object.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Update web link
tags:
- Web links
x-box-tag: web_links
"/web_links/{web_link_id}#add_shared_link":
put:
description: Adds a shared link to a web link.
operationId: put_web_links_id#add_shared_link
parameters:
- description: The ID of the web link.
example: "12345"
in: path
name: web_link_id
required: true
schema:
type: string
- description: |-
Explicitly request the `shared_link` fields
to be returned for this item.
example: shared_link
in: query
name: fields
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
shared_link:
description: |-
The settings for the shared link to create on the web link.
Use an empty object (`{}`) to use the default settings for shared
links.
properties:
access:
description: |-
The level of access for the shared link. This can be
restricted to anyone with the link (`open`), only people
within the company (`company`) and only those who
have been invited to the file (`collaborators`).
If not set, this field defaults to the access level specified
by the enterprise admin. To create a shared link with this
default setting pass the `shared_link` object with
no `access` field, for example `{ "shared_link": {} }`.
The `company` access level is only available to paid
accounts.
enum:
- open
- company
- collaborators
example: open
type: string
password:
description: |-
The password required to access the shared link. Set the
password to `null` to remove it.
A password can only be set when `access` is set to `open`.
example: do-not-use-this-password
type: string
permissions:
properties:
can_download:
description: |-
If the shared link allows for downloading of files.
This can only be set when `access` is set to
`open` or `company`.
example: true
type: boolean
can_edit:
description: This value can only be `true` is `type` is `file`.
example: false
type: boolean
can_preview:
description: |-
If the shared link allows for previewing of files.
This value is always `true`. For shared links on folders
this also applies to any items in the folder.
example: true
type: boolean
type: object
unshared_at:
description: |-
The timestamp at which this shared link will
expire. This field can only be set by
users with paid accounts. The value must be greater than the
current date and time.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
vanity_name:
description: |-
Defines a custom vanity name to use in the shared link URL,
for example `https://app.box.com/v/my-shared-link`.
Custom URLs should not be used when sharing sensitive content
as vanity URLs are a lot easier to guess than regular shared
links.
example: my-shared-link
minLength: 12
type: string
type: object
type: object
responses:
"200":
content:
application/json:
examples:
default:
value:
etag: "1"
id: "12345"
shared_link:
access: open
download_count: 0
download_url: https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf
effective_access: open
effective_permission: can_download
is_password_enabled: false
permissions:
can_download: true
can_edit: false
can_preview: true
preview_count: 0
unshared_at: 2020-09-21T10:34:41-07:00
url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1
vanity_name: null
vanity_url: null
type: web_link
schema:
$ref: "#/components/schemas/WebLink"
description: |-
Returns the base representation of a web link with a new shared
link attached.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned when there is an incorrect permission combination
"401":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when the access token provided in the `Authorization` header
is not recognized or not provided.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned if the user does not have all the permissions to complete the
update.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned if the file is not found, or the user does not
have access to the file.
"405":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned if the `file_id` is not in a recognized format.
"412":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Add shared link to web link
tags:
- Shared links (Web Links)
x-box-enable-explorer: true
x-box-sanitized: true
x-box-tag: shared_links_web_links
"/web_links/{web_link_id}#get_shared_link":
get:
description: Gets the information for a shared link on a web link.
operationId: get_web_links_id#get_shared_link
parameters:
- description: The ID of the web link.
example: "12345"
in: path
name: web_link_id
required: true
schema:
type: string
- description: |-
Explicitly request the `shared_link` fields
to be returned for this item.
example: shared_link
in: query
name: fields
required: true
schema:
type: string
responses:
"200":
content:
application/json:
examples:
default:
value:
etag: "1"
id: "12345"
shared_link:
access: open
download_count: 0
download_url: https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf
effective_access: open
effective_permission: can_download
is_password_enabled: false
permissions:
can_download: true
can_edit: false
can_preview: true
preview_count: 0
unshared_at: 2020-09-21T10:34:41-07:00
url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1
vanity_name: null
vanity_url: null
type: web_link
schema:
$ref: "#/components/schemas/WebLink"
description: |-
Returns the base representation of a web link with the
additional shared link information.
"401":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when the access token provided in the `Authorization` header
is not recognized or not provided.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned if the file is not found, or the user does not
have access to the file.
"405":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned if the `file_id` is not in a recognized format.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get shared link for web link
tags:
- Shared links (Web Links)
x-box-enable-explorer: true
x-box-sanitized: true
x-box-tag: shared_links_web_links
"/web_links/{web_link_id}#remove_shared_link":
put:
description: Removes a shared link from a web link.
operationId: put_web_links_id#remove_shared_link
parameters:
- description: The ID of the web link.
example: "12345"
in: path
name: web_link_id
required: true
schema:
type: string
- description: |-
Explicitly request the `shared_link` fields
to be returned for this item.
example: shared_link
in: query
name: fields
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
shared_link:
description: |-
By setting this value to `null`, the shared link
is removed from the web link.
example: null
nullable: true
type: object
type: object
responses:
"200":
content:
application/json:
examples:
default:
value:
etag: "1"
id: "12345"
shared_link: null
type: web_link
schema:
$ref: "#/components/schemas/WebLink"
description: |-
Returns a basic representation of a web link, with the
shared link removed.
"401":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when the access token provided in the `Authorization` header
is not recognized or not provided.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned if the user does not have all the permissions to complete the
update.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned if the file is not found, or the user does not
have access to the file.
"405":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned if the `file_id` is not in a recognized format.
"412":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Remove shared link from web link
tags:
- Shared links (Web Links)
x-box-enable-explorer: true
x-box-sanitized: true
x-box-tag: shared_links_web_links
"/web_links/{web_link_id}#update_shared_link":
put:
description: Updates a shared link on a web link.
operationId: put_web_links_id#update_shared_link
parameters:
- description: The ID of the web link.
example: "12345"
in: path
name: web_link_id
required: true
schema:
type: string
- description: |-
Explicitly request the `shared_link` fields
to be returned for this item.
example: shared_link
in: query
name: fields
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
shared_link:
description: The settings for the shared link to update.
properties:
access:
description: |-
The level of access for the shared link. This can be
restricted to anyone with the link (`open`), only people
within the company (`company`) and only those who
have been invited to the folder (`collaborators`).
If not set, this field defaults to the access level specified
by the enterprise admin. To create a shared link with this
default setting pass the `shared_link` object with
no `access` field, for example `{ "shared_link": {} }`.
The `company` access level is only available to paid
accounts.
enum:
- open
- company
- collaborators
example: open
type: string
password:
description: |-
The password required to access the shared link. Set the
password to `null` to remove it.
A password can only be set when `access` is set to `open`.
example: do-not-use-this-password
type: string
permissions:
properties:
can_download:
description: |-
If the shared link allows for downloading of files.
This can only be set when `access` is set to
`open` or `company`.
example: true
type: boolean
can_edit:
description: This value can only be `true` is `type` is `file`.
example: true
type: boolean
can_preview:
description: |-
If the shared link allows for previewing of files.
This value is always `true`. For shared links on folders
this also applies to any items in the folder.
example: true
type: boolean
type: object
unshared_at:
description: |-
The timestamp at which this shared link will
expire. This field can only be set by
users with paid accounts. The value must be greater than the
current date and time.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
vanity_name:
description: |-
Defines a custom vanity name to use in the shared link URL,
for example `https://app.box.com/v/my-shared-link`.
Custom URLs should not be used when sharing sensitive content
as vanity URLs are a lot easier to guess than regular shared
links.
example: my-shared-link
minLength: 12
type: string
type: object
type: object
responses:
"200":
content:
application/json:
examples:
default:
value:
etag: "1"
id: "12345"
shared_link:
access: open
download_count: 0
download_url: https://app.box.com/shared/static/kwio6b4ovt1264rnfbyqo1.pdf
effective_access: open
effective_permission: can_download
is_password_enabled: false
permissions:
can_download: true
can_edit: false
can_preview: true
preview_count: 0
unshared_at: 2020-09-21T10:34:41-07:00
url: https://app.box.com/s/kwio6b4ovt1264rnfbyqo1
vanity_name: null
vanity_url: null
type: web_link
schema:
$ref: "#/components/schemas/WebLink"
description: |-
Returns a basic representation of the web link, with the updated shared
link attached.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned when there is an incorrect permission combination
"401":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when the access token provided in the `Authorization` header
is not recognized or not provided.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned if the user does not have all the permissions to complete the
update.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned if the file is not found, or the user does not
have access to the file.
"405":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned if the `file_id` is not in a recognized format.
"412":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Update shared link on web link
tags:
- Shared links (Web Links)
x-box-enable-explorer: true
x-box-sanitized: true
x-box-tag: shared_links_web_links
"/web_links/{web_link_id}/trash":
delete:
description: |-
Permanently deletes a web link that is in the trash.
This action cannot be undone.
operationId: delete_web_links_id_trash
parameters:
- description: The ID of the web link.
example: "12345"
in: path
name: web_link_id
required: true
schema:
type: string
responses:
"204":
description: |-
Returns an empty response when the web link was
permanently deleted.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if the web link is not in the trash.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Permanently remove web link
tags:
- Trashed web links
x-box-tag: trashed_web_links
get:
description: Retrieves a web link that has been moved to the trash.
operationId: get_web_links_id_trash
parameters:
- description: The ID of the web link.
example: "12345"
in: path
name: web_link_id
required: true
schema:
type: string
- description: |-
A comma-separated list of attributes to include in the
response. This can be used to request fields that are
not normally returned in a standard response.
Be aware that specifying this parameter will have the
effect that none of the standard fields are returned in
the response unless explicitly specified, instead only
fields for the mini representation are returned, additional
to the fields requested.
example:
- id
- type
- name
explode: false
in: query
name: fields
required: false
schema:
items:
type: string
type: array
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/TrashWebLink"
description: |-
Returns the web link that was trashed,
including information about when the it
was moved to the trash.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if the web link is not in the trash.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get trashed web link
tags:
- Trashed web links
x-box-tag: trashed_web_links
/webhooks:
get:
description: |-
Returns all defined webhooks for the requesting application.
This API only returns webhooks that are applied to files or folders that are
owned by the authenticated user. This means that an admin can not see webhooks
created by a service account unless the admin has access to those folders, and
vice versa.
operationId: get_webhooks
parameters:
- description: |-
Defines the position marker at which to begin returning results. This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
in: query
name: marker
required: false
schema:
type: string
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Webhooks"
description: Returns a list of webhooks.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if the application does not
have the permission to manage webhooks.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List all webhooks
tags:
- Webhooks
x-box-tag: webhooks
post:
description: Creates a webhook.
operationId: post_webhooks
requestBody:
content:
application/json:
schema:
properties:
address:
description: The URL that is notified by this webhook
example: https://example.com/webhooks
type: string
target:
description: The item that will trigger the webhook
properties:
id:
description: The ID of the item to trigger a webhook
example: "1231232"
type: string
type:
description: The type of item to trigger a webhook
enum:
- file
- folder
example: file
type: string
type: object
triggers:
description: |-
An array of event names that this webhook is
to be triggered for
example:
- FILE.UPLOADED
items:
description: The event name that triggered this webhook
enum:
- FILE.UPLOADED
- FILE.PREVIEWED
- FILE.DOWNLOADED
- FILE.TRASHED
- FILE.DELETED
- FILE.RESTORED
- FILE.COPIED
- FILE.MOVED
- FILE.LOCKED
- FILE.UNLOCKED
- FILE.RENAMED
- COMMENT.CREATED
- COMMENT.UPDATED
- COMMENT.DELETED
- TASK_ASSIGNMENT.CREATED
- TASK_ASSIGNMENT.UPDATED
- METADATA_INSTANCE.CREATED
- METADATA_INSTANCE.UPDATED
- METADATA_INSTANCE.DELETED
- FOLDER.CREATED
- FOLDER.RENAMED
- FOLDER.DOWNLOADED
- FOLDER.RESTORED
- FOLDER.DELETED
- FOLDER.COPIED
- FOLDER.MOVED
- FOLDER.TRASHED
- WEBHOOK.DELETED
- COLLABORATION.CREATED
- COLLABORATION.ACCEPTED
- COLLABORATION.REJECTED
- COLLABORATION.REMOVED
- COLLABORATION.UPDATED
- SHARED_LINK.DELETED
- SHARED_LINK.CREATED
- SHARED_LINK.UPDATED
- SIGN_REQUEST.COMPLETED
- SIGN_REQUEST.DECLINED
- SIGN_REQUEST.EXPIRED
example: FILE.UPLOADED
title: Webhook Trigger
type: string
type: array
required:
- target
- triggers
- address
type: object
responses:
"201":
content:
application/json:
schema:
$ref: "#/components/schemas/Webhook"
description: Returns the new webhook object.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if the parameters were
incorrect.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if the application does not
have the permission to manage webhooks.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if the target item could
not be found
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if the a webhook for this
combination of target, application, and user
already exists.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Create webhook
tags:
- Webhooks
x-box-tag: webhooks
"/webhooks/{webhook_id}":
delete:
description: Deletes a webhook.
operationId: delete_webhooks_id
parameters:
- description: The ID of the webhook.
example: "3321123"
in: path
name: webhook_id
required: true
schema:
type: string
responses:
"204":
description: |-
An empty response will be returned when the webhook
was successfully deleted.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if the application does not
have the permission to manage webhooks.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if the webhook could not be found
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Remove webhook
tags:
- Webhooks
x-box-tag: webhooks
get:
description: Retrieves a specific webhook
operationId: get_webhooks_id
parameters:
- description: The ID of the webhook.
example: "3321123"
in: path
name: webhook_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Webhook"
description: Returns a webhook object
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if the application does not
have the permission to manage webhooks.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returns an error if the webhook could not be found
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get webhook
tags:
- Webhooks
x-box-tag: webhooks
put:
description: Updates a webhook.
operationId: put_webhooks_id
parameters:
- description: The ID of the webhook.
example: "3321123"
in: path
name: webhook_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
address:
description: The URL that is notified by this webhook
example: https://example.com/webhooks
type: string
target:
description: The item that will trigger the webhook
properties:
id:
description: The ID of the item to trigger a webhook
example: "1231232"
type: string
type:
description: The type of item to trigger a webhook
enum:
- file
- folder
example: file
type: string
type: object
triggers:
description: |-
An array of event names that this webhook is
to be triggered for
example:
- FILE.UPLOADED
items:
description: The event name that triggered this webhook
enum:
- FILE.UPLOADED
- FILE.PREVIEWED
- FILE.DOWNLOADED
- FILE.TRASHED
- FILE.DELETED
- FILE.RESTORED
- FILE.COPIED
- FILE.MOVED
- FILE.LOCKED
- FILE.UNLOCKED
- FILE.RENAMED
- COMMENT.CREATED
- COMMENT.UPDATED
- COMMENT.DELETED
- TASK_ASSIGNMENT.CREATED
- TASK_ASSIGNMENT.UPDATED
- METADATA_INSTANCE.CREATED
- METADATA_INSTANCE.UPDATED
- METADATA_INSTANCE.DELETED
- FOLDER.CREATED
- FOLDER.RENAMED
- FOLDER.DOWNLOADED
- FOLDER.RESTORED
- FOLDER.DELETED
- FOLDER.COPIED
- FOLDER.MOVED
- FOLDER.TRASHED
- WEBHOOK.DELETED
- COLLABORATION.CREATED
- COLLABORATION.ACCEPTED
- COLLABORATION.REJECTED
- COLLABORATION.REMOVED
- COLLABORATION.UPDATED
- SHARED_LINK.DELETED
- SHARED_LINK.CREATED
- SHARED_LINK.UPDATED
- SIGN_REQUEST.COMPLETED
- SIGN_REQUEST.DECLINED
- SIGN_REQUEST.EXPIRED
example: FILE.UPLOADED
title: Webhook Trigger
type: string
type: array
type: object
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Webhook"
description: Returns the new webhook object.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if the parameters were
incorrect.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if the application does not
have the permission to manage webhooks.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if the target item or webhook
could not be found
"409":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returns an error if the a webhook for this
combination of target, application, and user
already exists.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Update webhook
tags:
- Webhooks
x-box-tag: webhooks
/workflows:
get:
description: |-
Returns list of workflows that act on a given `folder ID`, and
have a flow with a trigger type of `WORKFLOW_MANUAL_START`.
You application must be authorized to use the `Manage Box Relay` application
scope within the developer console in to use this endpoint.
operationId: get_workflows
parameters:
- description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting this folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folder/123`
the `folder_id` is `123`.
The root folder of a Box account is
always represented by the ID `0`.
example: "12345"
in: query
name: folder_id
required: true
schema:
nullable: false
type: string
- description: Type of trigger to search for.
example: WORKFLOW_MANUAL_START
in: query
name: trigger_type
required: false
schema:
nullable: false
type: string
- description: The maximum number of items to return per page.
example: 1000
in: query
name: limit
required: false
schema:
format: int64
maximum: 1000
type: integer
- description: |-
Defines the position marker at which to begin returning results. This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
in: query
name: marker
required: false
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/Workflows"
description: Returns the workflow.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: Returned if the trigger type is not `WORKFLOW_MANUAL_START`.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned if the folder is not found, or the user does not
have access to the folder.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: List workflows
tags:
- Workflows
x-box-tag: workflows
"/workflows/{workflow_id}/start":
post:
description: |-
Initiates a flow with a trigger type of `WORKFLOW_MANUAL_START`.
You application must be authorized to use the `Manage Box Relay` application
scope within the developer console.
operationId: post_workflows_id_start
parameters:
- description: The ID of the workflow.
example: "12345"
in: path
name: workflow_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
files:
description: |-
The array of files for which the workflow should start. All files
must be in the workflow's configured folder.
items:
description: A file the workflow should start for
properties:
id:
description: The id of the file
example: "12345678"
type: string
type:
description: The type of the file object
enum:
- file
example: file
type: string
type: object
type: array
flow:
description: The flow that will be triggered
properties:
id:
description: The id of the flow
example: "123456789"
type: string
type:
description: The type of the flow object
example: flow
type: string
type: object
folder:
description: The folder object for which the workflow is configured.
properties:
id:
description: The id of the folder
example: "87654321"
type: string
type:
description: The type of the folder object
enum:
- folder
example: folder
type: string
type: object
outcomes:
description: A list of outcomes required to be configured at start time.
items:
description: |-
A configurable outcome the workflow should complete. If you
have a `task_completion_rule`, you may input `all_assignees` or
`any_assignee` in the `variable_value` field. Similarly, if you
have a `collaborator_role`, you may input `editor`, `viewer`,
`previewer`, `uploader`, `previewer uploader`, `viewer uploader`
, `co-owner` in the `variable_value` field.
properties:
id:
description: The id of the outcome
example: "890375782"
type: string
parameter:
description: |-
This is a placeholder example for various objects that
can be passed in - refer to the guides section to find
out more information.
example: placeholder
type: string
type:
description: The type of the outcome object
enum:
- outcome
example: outcome
type: string
type: object
type: array
type:
description: The type of the parameters object
enum:
- workflow_parameters
example: workflow_parameters
type: string
required:
- flow
- files
- folder
type: object
responses:
"204":
description: Starts the workflow.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Starts workflow based on request body
tags:
- Workflows
x-box-tag: workflows
/zip_downloads:
post:
description: |-
Creates a request to download multiple files and folders as a single `zip`
archive file. This API does not return the archive but instead performs all
the checks to ensure that the user has access to all the items, and then
returns a `download_url` and a `status_url` that can be used to download the
archive.
The limit for an archive is either the Account's upload limit or
10,000 files, whichever is met first
operationId: post_zip_downloads
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/ZipDownloadRequest"
responses:
"202":
content:
application/json:
examples:
default:
value:
download_url: https://dl.boxcloud.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/content
expires_at: 2020-07-22T11:26:08Z
name_conflicts:
- - download_name: 3aa6a7.pdf
id: "12345"
original_name: Report.pdf
type: file
- download_name: 5d53f2.pdf
id: "34325"
original_name: Report.pdf
type: file
status_url: https://api.box.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/status
schema:
$ref: "#/components/schemas/ZipDownload"
description: |-
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.
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"401":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when the access token provided in the `Authorization` header
is not recognized or not provided.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when an authorization header is provided but the user does not
have access to the items.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Create zip download
tags:
- Zip Downloads
x-box-reference-category: zip_downloads
x-box-tag: zip_downloads
"/zip_downloads/{zip_download_id}/content":
get:
description: |-
Returns the contents of a `zip` archive in binary format. This URL does not
require any form of authentication and could be used in a user's browser to
download the archive to a user's device.
By default, this URL is only valid for a few seconds from the creation of
the request for this archive. Once a download has started it can not be
stopped and resumed, instead a new request for a zip archive would need to
be created.
The URL of this endpoint should not be considered as fixed. Instead, use
the [Create zip download](e://post_zip_downloads) API to request to create a
`zip` archive, and then follow the `download_url` field in the response to
this endpoint.
operationId: get_zip_downloads_id_content
parameters:
- description: The unique identifier that represent this `zip` archive.
example: Lu6fA9Ob-jyysp3AAvMF4AkLEwZwAYbL=tgj2zIC=eK9RvJnJbjJl9rNh2qBgHDpyOCAOhpM=vajg2mKq8Mdd
in: path
name: zip_download_id
required: true
schema:
type: string
responses:
"200":
content:
application/octet-stream:
schema:
description: |-
The binary content of the archive, which will include the items
requested for this download.
format: binary
type: string
description: |-
Returns the content of the items requested for this download, formatted as
a stream of files and folders in a `zip` archive.
headers:
Content-Disposition:
description: The name of the archive to be downloaded
schema:
example: attachment;filename="Avatars.zip";filename*=UTF-8''Avatars.zip
type: string
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
"429":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
security: []
servers:
- description: |-
An opaque server URL for downloading zip downloads. The format
of this URL might change over time.
url: https://dl.boxcloud.com/2.0
summary: Download zip archive
tags:
- Zip Downloads
x-box-reference-category: zip_downloads
x-box-tag: zip_downloads
"/zip_downloads/{zip_download_id}/status":
get:
description: |-
Returns the download status of a `zip` archive, allowing an application to
inspect the progress of the download as well as the number of items that
might have been skipped.
This endpoint can only be accessed once the download has started.
Subsequently this endpoint is valid for 12 hours from the start of the
download.
The URL of this endpoint should not be considered as fixed. Instead, use
the [Create zip download](e://post_zip_downloads) API to request to create a
`zip` archive, and then follow the `status_url` field in the response to
this endpoint.
operationId: get_zip_downloads_id_status
parameters:
- description: The unique identifier that represent this `zip` archive.
example: Lu6fA9Ob-jyysp3AAvMF4AkLEwZwAYbL=tgj2zIC=eK9RvJnJbjJl9rNh2qBgHDpyOCAOhpM=vajg2mKq8Mdd
in: path
name: zip_download_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: "#/components/schemas/ZipDownloadStatus"
description: Returns the status of the `zip` archive that is being downloaded.
"401":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when the access token provided in the `Authorization` header
is not recognized or not provided.
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
Returned when an authorization header is provided but the user does not
have access to the items.
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: |-
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.
default:
content:
application/json:
schema:
$ref: "#/components/schemas/ClientError"
description: An unexpected client error.
summary: Get zip download status
tags:
- Zip Downloads
x-box-reference-category: zip_downloads
x-box-tag: zip_downloads
components:
schemas:
AccessToken:
description: A token that can be used to make authenticated API calls.
properties:
access_token:
description: The requested access token.
example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ
format: token
type: string
expires_in:
description: The time in seconds in seconds by which this token will expire.
example: 3600
format: int64
type: integer
issued_token_type:
description: |-
The type of downscoped access token returned. This is only
returned if an access token has been downscoped.
enum:
- urn:ietf:params:oauth:token-type:access_token
example: urn:ietf:params:oauth:token-type:access_token
format: urn
type: string
refresh_token:
description: |-
The refresh token for this access token, which can be used
to request a new access token when the current one expires.
example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ
format: token
type: string
restricted_to:
description: |-
The permissions that this access token permits,
providing a list of resources (files, folders, etc)
and the scopes permitted for each of those resources.
items:
$ref: "#/components/schemas/FileScope"
type: array
token_type:
description: The type of access token returned.
enum:
- bearer
example: bearer
type: string
title: Access token
type: object
x-box-resource-id: access_token
x-box-tag: authorization
Classification:
description: |-
An instance of the classification metadata template, containing
the classification applied to the file or folder.
To get more details about the classification applied to an item,
request the classification metadata template.
properties:
$canEdit:
description: Whether an end user can change the classification.
example: true
type: boolean
$parent:
description: |-
The identifier of the item that this metadata instance
has been attached to. This combines the `type` and the `id`
of the parent in the form `{type}_{id}`.
example: folder_59449484661,
type: string
$scope:
description: |-
The scope of the enterprise that this classification has been
applied for.
This will be in the format `enterprise_{enterprise_id}`.
example: enterprise_27335
type: string
$template:
description: "`securityClassification-6VMVochwUWo`"
enum:
- securityClassification-6VMVochwUWo
example: securityClassification-6VMVochwUWo
type: string
$type:
description: |-
The unique ID of this classification instance. This will be include
the name of the classification template and a unique ID.
example: securityClassification-6VMVochwUWo-fd31537a-0f95-4d86-9f2b-5974a29978f8
type: string
$typeVersion:
description: |-
The version of the metadata template. This version starts at 0 and
increases every time the template is updated. This is mostly for internal
use.
example: 5
type: number
$version:
description: |-
The version of the metadata instance. This version starts at 0 and
increases every time a classification is updated.
example: 1
type: integer
Box__Security__Classification__Key:
description: The name of the classification applied to the item.
example: Sensitive
type: string
title: Classification
type: object
x-box-resource-id: classification
x-box-tag: classifications
ClassificationTemplate:
description: |-
A metadata template that holds the security classifications
defined by an enterprise.
properties:
copyInstanceOnItemCopy:
description: |-
Classifications are always copied along when the file or folder is
copied.
example: true
type: boolean
displayName:
description: The name of this template as shown in web and mobile interfaces.
enum:
- Classification
example: Classification
type: string
fields:
description: |-
A list of fields for this classification template. This includes
only one field, the `Box__Security__Classification__Key`, which defines
the different classifications available in this enterprise.
items:
description: |-
The metadata template field that represents the available
classifications.
properties:
displayName:
description: "`Classification`"
enum:
- Classification
example: Classification
type: string
hidden:
description: Classifications are always visible to web and mobile users.
example: false
type: boolean
id:
description: The unique ID of the field.
example: 822227e0-47a5-921b-88a8-494760b2e6d2
type: string
key:
description: "`Box__Security__Classification__Key`"
enum:
- Box__Security__Classification__Key
example: Box__Security__Classification__Key
type: string
options:
description: A list of classifications available in this enterprise.
items:
description: A single classification available in this enterprise.
properties:
id:
description: The unique ID of this classification.
example: 46aea176-3483-4431-856c-6b5b13d1cc50
type: string
key:
description: The display name and key for this classification.
example: Sensitive
type: string
staticConfig:
description: Additional information about the classification.
properties:
classification:
description: |-
Additional information about the classification.
This is not an exclusive list of properties, and
more object fields might be returned. These fields
are used for internal Box Shield and Box Governance
purposes and no additional value must be derived from
these fields.
properties:
classificationDefinition:
description: A longer description of the classification.
example: Sensitive information
type: string
colorID:
description: |-
An internal Box identifier used to assign a color to
a classification label.
Mapping between a `colorID` and a color may change
without notice. Currently, the color mappings are as
follows.
* `0`: Yellow
* `1`: Orange
* `2`: Watermelon red
* `3`: Purple rain
* `4`: Light blue
* `5`: Dark blue
* `6`: Light green
* `7`: Gray
example: 4
type: number
type: object
type: object
type: object
minItems: 1
type: array
type:
description: "`enum`"
enum:
- enum
example: enum
type: string
type: object
maxItems: 1
minItems: 1
type: array
hidden:
description: This template is always available in web and mobile interfaces.
example: false
type: boolean
id:
description: The ID of the classification template.
example: 58063d82-4128-7b43-bba9-92f706befcdf
type: string
scope:
description: |-
The scope of the classification template. This is in the format
`enterprise_{id}` where the `id` is the enterprise ID.
example: enterprise_123456
type: string
templateKey:
description: "`securityClassification-6VMVochwUWo`"
enum:
- securityClassification-6VMVochwUWo
example: securityClassification-6VMVochwUWo
type: string
type:
description: "`metadata_template`"
enum:
- metadata_template
example: metadata_template
nullable: false
type: string
required:
- type
title: Classification Template
type: object
x-box-resource-id: classification_template
x-box-tag: classifications
ClientError:
description: A generic error
properties:
code:
description: A Box-specific error code
enum:
- created
- accepted
- no_content
- redirect
- not_modified
- bad_request
- unauthorized
- forbidden
- not_found
- method_not_allowed
- conflict
- precondition_failed
- too_many_requests
- internal_server_error
- unavailable
- item_name_invalid
- insufficient_scope
example: item_name_invalid
type: string
context_info:
description: |-
A free-form object that contains additional context
about the error. The possible fields are defined on
a per-endpoint basis. `message` is only one example.
properties:
message:
description: More details on the error.
example: Something went wrong.
type: string
type: object
help_url:
description: A URL that links to more information about why this error occurred.
example: https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/
nullable: false
type: string
message:
description: A short message describing the error.
example: Method Not Allowed
nullable: false
type: string
request_id:
description: |-
A unique identifier for this response, which can be used
when contacting Box support.
example: abcdef123456
nullable: false
type: string
status:
description: The HTTP status of the response.
example: 400
format: int32
nullable: false
type: integer
type:
description: "`error`"
enum:
- error
example: error
nullable: false
type: string
title: Client error
type: object
x-box-resource-id: client_error
Collaboration:
description: |-
Collaborations define access permissions for users and groups to files and
folders, similar to access control lists. A collaboration object grants a
user or group access to a file or folder with permissions defined by a
specific role.
properties:
acceptance_requirements_status:
properties:
strong_password_requirement:
properties:
enterprise_has_strong_password_required_for_external_users:
description: |-
Whether or not the enterprise that owns the content requires
a strong password to collaborate on the content.
example: true
type: boolean
user_has_strong_password:
description: |-
Whether or not the user has a strong password set for their
account. The field is `null` when a strong password is not
required.
example: true
nullable: true
type: boolean
type: object
terms_of_service_requirement:
properties:
is_accepted:
description: |-
Whether or not the terms of service have been accepted. The
field is `null` when there is no terms of service required.
example: true
nullable: true
type: boolean
terms_of_service:
allOf:
- $ref: "#/components/schemas/TermsOfService--Base"
- description: |-
The terms of service that must be accepted before the
collaboration can be accepted. The field is `null` when
there is no terms of service required.
type: object
two_factor_authentication_requirement:
properties:
enterprise_has_two_factor_auth_enabled:
description: |-
Whether or not the enterprise that owns the content requires
two-factor authentication to be enabled in order to
collaborate on the content.
example: true
type: boolean
user_has_two_factor_authentication_enabled:
description: |-
Whether or not the user has two-factor authentication
enabled. The field is `null` when two-factor
authentication is not required.
example: true
nullable: true
type: boolean
type: object
type: object
accessible_by:
allOf:
- $ref: "#/components/schemas/User--Collaborations"
- description: The user or group that is granted access.
acknowledged_at:
description: |-
When the `status` of the collaboration object changed to
`accepted` or `rejected`.
example: 2012-12-12T10:55:20-08:00
format: date-time
type: string
created_at:
description: When the collaboration object was created.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
created_by:
allOf:
- $ref: "#/components/schemas/User--Collaborations"
- description: The user who created the collaboration object.
- example:
- id: 33224412
- type: user
- login: dylan@example.com
- name: Dylan Smith
expires_at:
description: |-
When the collaboration will expire, or `null` if no expiration
date is set.
example: 2012-12-26T10:53:43-08:00
format: date-time
nullable: true
type: string
id:
description: The unique identifier for this collaboration.
example: "12345678"
type: string
invite_email:
description: |-
The email address used to invite an unregistered collaborator, if
they are not a registered user.
example: john@example.com
nullable: true
type: string
item:
allOf:
- oneOf:
- $ref: "#/components/schemas/File"
- $ref: "#/components/schemas/Folder"
- $ref: "#/components/schemas/WebLink"
- description: |-
The file or folder to which access is granted. The field is
`null` when the collaboration `status` is `pending`.
nullable: true
modified_at:
description: When the collaboration object was last modified.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
role:
description: The level of access granted.
enum:
- editor
- viewer
- previewer
- uploader
- previewer uploader
- viewer uploader
- co-owner
- owner
example: editor
type: string
status:
description: |-
The status of the collaboration invitation. If the status
is `pending`, `login` and `name` return an empty string.
enum:
- accepted
- pending
- rejected
example: accepted
type: string
type:
description: "`collaboration`"
enum:
- collaboration
example: collaboration
type: string
title: Collaboration
type: object
x-box-resource-id: collaboration
x-box-tag: user_collaborations
CollaborationAllowlistEntries:
allOf:
- description: |-
The part of an API response that describes marker
based pagination
properties:
limit:
description: |-
The limit that was used for these entries. This will be the same as the
`limit` query parameter unless that value exceeded the maximum value
allowed. The maximum value varies by API.
example: 1000
format: int64
type: integer
next_marker:
description: The marker for the start of the next page of results.
example: 3000
format: int64
type: integer
prev_marker:
description: The marker for the start of the previous page of results.
example: 1000
format: int64
type: integer
type: object
- properties:
entries:
items:
$ref: "#/components/schemas/CollaborationAllowlistEntry"
type: array
description: A list of allowed domains for collaboration.
title: Allowed collaboration domains
type: object
x-box-resource-id: collaboration_allowlist_entries
x-box-tag: collaboration_allowlist_entries
CollaborationAllowlistEntry:
description: |-
An entry that describes an approved domain for which users can collaborate
with files and folders in your enterprise or vice versa.
properties:
created_at:
description: The time the entry was created at
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
direction:
description: The direction of the collaborations to allow.
enum:
- inbound
- outbound
- both
example: both
type: string
domain:
description: The whitelisted domain
example: example.com
type: string
enterprise:
allOf:
- description: A representation of a Box enterprise
properties:
id:
description: The unique identifier for this enterprise.
example: "11446498"
type: string
name:
description: The name of the enterprise
example: Acme Inc.
type: string
type:
description: "`enterprise`"
enum:
- enterprise
example: enterprise
type: string
title: Enterprise
type: object
- description: The enterprise this list is applied to
id:
description: The unique identifier for this entry
example: "11446498"
type: string
type:
description: "`collaboration_whitelist_entry`"
enum:
- collaboration_whitelist_entry
example: collaboration_whitelist_entry
type: string
title: Allowed collaboration domain
type: object
x-box-resource-id: collaboration_allowlist_entry
x-box-tag: collaboration_allowlist_entries
CollaborationAllowlistExemptTarget:
description: |-
The user that is exempt from any of the restrictions
imposed by the list of allowed collaboration domains for this enterprise.
properties:
created_at:
description: The time the entry was created
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
enterprise:
allOf:
- description: A representation of a Box enterprise
properties:
id:
description: The unique identifier for this enterprise.
example: "11446498"
type: string
name:
description: The name of the enterprise
example: Acme Inc.
type: string
type:
description: "`enterprise`"
enum:
- enterprise
example: enterprise
type: string
title: Enterprise
type: object
- description: The enterprise this entry belongs to
id:
description: The unique identifier for this exemption
example: "11446498"
type: string
modified_at:
description: The time the entry was modified
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
type:
description: "`collaboration_whitelist`"
enum:
- collaboration_whitelist
example: collaboration_whitelist
type: string
user:
allOf:
- description: A representation of a Box enterprise
properties:
id:
description: The unique identifier for this enterprise.
example: "11446498"
type: string
name:
description: The name of the enterprise
example: Acme Inc.
type: string
type:
description: "`enterprise`"
enum:
- enterprise
example: enterprise
type: string
title: Enterprise
type: object
- description: The user that has been exempt
title: Allowed collaboration domains user exemption
type: object
x-box-resource-id: collaboration_allowlist_exempt_target
x-box-tag: collaboration_allowlist_exempt_targets
CollaborationAllowlistExemptTargets:
allOf:
- description: |-
The part of an API response that describes marker
based pagination
properties:
limit:
description: |-
The limit that was used for these entries. This will be the same as the
`limit` query parameter unless that value exceeded the maximum value
allowed. The maximum value varies by API.
example: 1000
format: int64
type: integer
next_marker:
description: The marker for the start of the next page of results.
example: 3000
format: int64
type: integer
prev_marker:
description: The marker for the start of the previous page of results.
example: 1000
format: int64
type: integer
type: object
- properties:
entries:
items:
$ref: "#/components/schemas/CollaborationAllowlistExemptTarget"
type: array
description: |-
A list of users that is exempt from any of the restrictions
imposed by the list of allowed collaboration domains for this enterprise.
title: Allowed collaboration domains user exemptions
type: object
x-box-resource-id: collaboration_allowlist_exempt_targets
x-box-tag: collaboration_allowlist_exempt_targets
Collaborations:
allOf:
- description: The part of an API response that describes pagination
properties:
limit:
description: |-
The limit that was used for these entries. This will be the same as the
`limit` query parameter unless that value exceeded the maximum value
allowed. The maximum value varies by API.
example: 1000
format: int64
type: integer
offset:
description: |-
The 0-based offset of the first entry in this set. This will be the same
as the `offset` query parameter.
This field is only returned for calls that use offset-based pagination.
For marker-based paginated APIs, this field will be omitted.
example: 2000
format: int64
type: integer
order:
description: |-
The order by which items are returned.
This field is only returned for calls that use offset-based pagination.
For marker-based paginated APIs, this field will be omitted.
items:
description: The order in which a pagination is ordered
properties:
by:
description: The field to order by
example: type
type: string
direction:
description: The direction to order by, either ascending or descending
enum:
- ASC
- DESC
example: ASC
type: string
type: object
type: array
total_count:
description: |-
One greater than the offset of the last entry in the entire collection.
The total number of entries in the collection may be less than
`total_count`.
This field is only returned for calls that use offset-based pagination.
For marker-based paginated APIs, this field will be omitted.
example: 5000
format: int64
type: integer
type: object
- properties:
entries:
items:
$ref: "#/components/schemas/Collaboration"
type: array
description: A list of collaborations
title: Collaborations
type: object
x-box-resource-id: collaborations
x-box-tag: user_collaborations
Collection:
description: |-
A collection of items, including files and folders.
Currently, the only collection available
is the `favorites` collection.
The contents of a collection can be explored in a
similar way to which the contents of a folder is
explored.
properties:
collection_type:
description: |-
The type of the collection. This is used to
determine the proper visual treatment for
collections.
enum:
- favorites
example: favorites
type: string
id:
description: The unique identifier for this collection.
example: "11446498"
type: string
name:
description: The name of the collection.
enum:
- Favorites
example: Favorites
type: string
type:
description: "`collection`"
enum:
- collection
example: collection
type: string
title: Collection
type: object
x-box-resource-id: collection
x-box-tag: collections
Collections:
allOf:
- description: The part of an API response that describes pagination
properties:
limit:
description: |-
The limit that was used for these entries. This will be the same as the
`limit` query parameter unless that value exceeded the maximum value
allowed. The maximum value varies by API.
example: 1000
format: int64
type: integer
offset:
description: |-
The 0-based offset of the first entry in this set. This will be the same
as the `offset` query parameter.
This field is only returned for calls that use offset-based pagination.
For marker-based paginated APIs, this field will be omitted.
example: 2000
format: int64
type: integer
order:
description: |-
The order by which items are returned.
This field is only returned for calls that use offset-based pagination.
For marker-based paginated APIs, this field will be omitted.
items:
description: The order in which a pagination is ordered
properties:
by:
description: The field to order by
example: type
type: string
direction:
description: The direction to order by, either ascending or descending
enum:
- ASC
- DESC
example: ASC
type: string
type: object
type: array
total_count:
description: |-
One greater than the offset of the last entry in the entire collection.
The total number of entries in the collection may be less than
`total_count`.
This field is only returned for calls that use offset-based pagination.
For marker-based paginated APIs, this field will be omitted.
example: 5000
format: int64
type: integer
type: object
- properties:
entries:
items:
$ref: "#/components/schemas/Collection"
type: array
description: A list of collections
title: Collections
type: object
x-box-resource-id: collections
x-box-tag: collections
Comment:
allOf:
- $ref: "#/components/schemas/Comment--Base"
- properties:
created_at:
description: The time this comment was created
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
created_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: |-
A mini user object representing the author of the
comment
is_reply_comment:
description: |-
Whether or not this comment is a reply to another
comment
example: true
type: boolean
item:
allOf:
- description: The bare basic reference for an object
properties:
id:
description: The unique identifier for this object
example: "11446498"
type: string
type:
description: The type for this object
example: file
type: string
title: Reference
type: object
- description: The file this comment was placed on
message:
description: The text of the comment, as provided by the user
example: "@Aaron Levie these tigers are cool!"
type: string
modified_at:
description: The time this comment was last modified
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
description: Standard representation of a comment.
title: Comment
type: object
x-box-resource-id: comment
x-box-variant: standard
Comment--Base:
description: Base representation of a comment.
properties:
id:
description: The unique identifier for this comment.
example: "11446498"
type: string
type:
description: "`comment`"
enum:
- comment
example: comment
type: string
title: Comment (Base)
type: object
x-box-resource-id: comment--base
x-box-sanitized: true
x-box-tag: comments
x-box-variant: base
x-box-variants:
- base
- standard
- full
Comment--Full:
allOf:
- $ref: "#/components/schemas/Comment"
- properties:
tagged_message:
description: |-
The string representing the comment text with
@mentions included. @mention format is @[id:username]
where `id` is user's Box ID and `username` is
their display name.
example: "@[1234567:Aaron Levie] these tigers are cool!"
type: string
description: |-
Comments are messages created on files. Comments
can be made independently or created as responses to other
comments
title: Comment (Full)
type: object
x-box-resource-id: comment--full
x-box-variant: full
Comments:
allOf:
- description: The part of an API response that describes pagination
properties:
limit:
description: |-
The limit that was used for these entries. This will be the same as the
`limit` query parameter unless that value exceeded the maximum value
allowed. The maximum value varies by API.
example: 1000
format: int64
type: integer
offset:
description: |-
The 0-based offset of the first entry in this set. This will be the same
as the `offset` query parameter.
This field is only returned for calls that use offset-based pagination.
For marker-based paginated APIs, this field will be omitted.
example: 2000
format: int64
type: integer
order:
description: |-
The order by which items are returned.
This field is only returned for calls that use offset-based pagination.
For marker-based paginated APIs, this field will be omitted.
items:
description: The order in which a pagination is ordered
properties:
by:
description: The field to order by
example: type
type: string
direction:
description: The direction to order by, either ascending or descending
enum:
- ASC
- DESC
example: ASC
type: string
type: object
type: array
total_count:
description: |-
One greater than the offset of the last entry in the entire collection.
The total number of entries in the collection may be less than
`total_count`.
This field is only returned for calls that use offset-based pagination.
For marker-based paginated APIs, this field will be omitted.
example: 5000
format: int64
type: integer
type: object
- properties:
entries:
items:
$ref: "#/components/schemas/Comment"
type: array
description: A list of comments
title: Comments
type: object
x-box-resource-id: comments
x-box-tag: comments
ConflictError:
allOf:
- $ref: "#/components/schemas/ClientError"
- properties:
context_info:
properties:
conflicts:
description: A list of the file conflicts that caused this error.
items:
$ref: "#/components/schemas/FileConflict"
type: array
type: object
description: |-
The error that occurs when a file can not be created due
to a conflict.
title: Conflict error
type: object
x-box-resource-id: conflict_error
x-box-tag: uploads
DevicePinner:
description: |-
Device pins allow enterprises to control what devices can
use native Box applications.
properties:
id:
description: The unique identifier for this device pin.
example: "11446498"
type: string
owned_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user that the device pin belongs to
product_name:
description: The type of device being pinned
example: iPad
type: string
type:
description: "`device_pinner`"
enum:
- device_pinner
example: device_pinner
type: string
title: Device pinner
type: object
x-box-resource-id: device_pinner
x-box-tag: device_pinners
DevicePinners:
description: A list of device pins
properties:
entries:
items:
$ref: "#/components/schemas/DevicePinner"
type: array
limit:
default: 100
description: |-
The limit that was used for these entries. This will be the same as the
`limit` query parameter unless that value exceeded the maximum value
allowed.
example: 200
format: int64
type: integer
next_marker:
description: The marker for the start of the next page of results.
example: 3000
format: int64
type: integer
order:
description: The order by which items are returned.
items:
description: The order in which a pagination is ordered
properties:
by:
description: The field that is ordered by
enum:
- id
example: id
type: string
direction:
description: The direction to order by, either ascending or descending
enum:
- asc
- desc
example: asc
type: string
type: object
type: array
title: Device pinners
type: object
x-box-resource-id: device_pinners
x-box-tag: device_pinners
EmailAlias:
description: An email alias for a user.
properties:
email:
description: The email address
example: alias@example.com
type: string
id:
description: The unique identifier for this object
example: "11446498"
type: string
is_confirmed:
description: Whether the email address has been confirmed
example: true
type: boolean
type:
description: "`email_alias`"
enum:
- email_alias
example: email_alias
type: string
title: Email alias
type: object
x-box-resource-id: email_alias
x-box-tag: email_aliases
EmailAliases:
description: A list of email aliases
properties:
entries:
items:
$ref: "#/components/schemas/EmailAlias"
type: array
total_count:
description: The number of email aliases.
example: 5000
format: int64
type: integer
title: Email aliases
type: object
x-box-resource-id: email_aliases
x-box-tag: email_aliases
Enterprise--Base:
description: |-
A mini representation of a enterprise, used when
nested within another resource.
properties:
id:
description: The unique identifier for this enterprise
example: "1910967"
type: string
type:
description: "`enterprise`"
enum:
- enterprise
example: enterprise
nullable: false
type: string
title: Enterprise (Base)
type: object
x-box-resource-id: enterprise--base
x-box-variant: base
x-box-variants:
- base
- mini
- standard
- full
Event:
description: The description of an event that happened within Box
properties:
additional_details:
description: |-
This object provides additional information about the event if available.
This can include how a user performed an event as well as additional
information to correlate an event to external KeySafe logs. Not all events
have an `additional_details` object. This object is only available in the
Enterprise Events.
example:
key: value
type: object
created_at:
description: When the event object was created
example: 2022-12-12T10:53:43-08:00
format: date-time
type: string
created_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: |-
The user that performed the action represented by the event.
Some events may be performed by users not logged into Box.
In that case, not all attributes of the object are populated and the
event is attributed to a unknown user (`user_id = 2`)
event_id:
description: The ID of the event object. You can use this to detect duplicate events
example: f82c3ba03e41f7e8a7608363cc6c0390183c3f83
type: string
event_type:
allOf:
- description: An event type that can trigger an event
enum:
- ACCESS_GRANTED
- ACCESS_REVOKED
- ADD_DEVICE_ASSOCIATION
- ADD_LOGIN_ACTIVITY_DEVICE
- ADMIN_LOGIN
- APPLICATION_CREATED
- APPLICATION_PUBLIC_KEY_ADDED
- APPLICATION_PUBLIC_KEY_DELETED
- CHANGE_ADMIN_ROLE
- CHANGE_FOLDER_PERMISSION
- COLLABORATION_ACCEPT
- COLLABORATION_EXPIRATION
- COLLABORATION_INVITE
- COLLABORATION_REMOVE
- COLLABORATION_ROLE_CHANGE
- COLLAB_ADD_COLLABORATOR
- COLLAB_INVITE_COLLABORATOR
- COLLAB_REMOVE_COLLABORATOR
- COLLAB_ROLE_CHANGE
- COMMENT_CREATE
- COMMENT_DELETE
- CONTENT_ACCESS
- CONTENT_WORKFLOW_ABNORMAL_DOWNLOAD_ACTIVITY
- CONTENT_WORKFLOW_AUTOMATION_ADD
- CONTENT_WORKFLOW_AUTOMATION_DELETE
- CONTENT_WORKFLOW_POLICY_ADD
- CONTENT_WORKFLOW_SHARING_POLICY_VIOLATION
- CONTENT_WORKFLOW_UPLOAD_POLICY_VIOLATION
- COPY
- DATA_RETENTION_CREATE_RETENTION
- DATA_RETENTION_REMOVE_RETENTION
- DELETE
- DELETE_USER
- DEVICE_TRUST_CHECK_FAILED
- DOWNLOAD
- EDIT
- EDIT_USER
- EMAIL_ALIAS_CONFIRM
- EMAIL_ALIAS_REMOVE
- ENABLE_TWO_FACTOR_AUTH
- ENTERPRISE_APP_AUTHORIZATION_UPDATE
- FAILED_LOGIN
- FILE_MARKED_MALICIOUS
- FILE_WATERMARKED_DOWNLOAD
- GROUP_ADD_ITEM
- GROUP_ADD_USER
- GROUP_CREATION
- GROUP_DELETION
- GROUP_EDITED
- GROUP_REMOVE_ITEM
- GROUP_REMOVE_USER
- ITEM_COPY
- ITEM_CREATE
- ITEM_DOWNLOAD
- ITEM_MAKE_CURRENT_VERSION
- ITEM_MODIFY
- ITEM_MOVE
- ITEM_OPEN
- ITEM_PREVIEW
- ITEM_RENAME
- ITEM_SHARED
- ITEM_SHARED_CREATE
- ITEM_SHARED_UNSHARE
- ITEM_SHARED_UPDATE
- ITEM_SYNC
- ITEM_TRASH
- ITEM_UNDELETE_VIA_TRASH
- ITEM_UNSYNC
- ITEM_UPLOAD
- LEGAL_HOLD_ASSIGNMENT_CREATE
- LEGAL_HOLD_ASSIGNMENT_DELETE
- LEGAL_HOLD_POLICY_CREATE
- LEGAL_HOLD_POLICY_DELETE
- LEGAL_HOLD_POLICY_UPDATE
- LOCK
- LOCK_CREATE
- LOCK_DESTROY
- LOGIN
- MASTER_INVITE_ACCEPT
- MASTER_INVITE_REJECT
- METADATA_INSTANCE_CREATE
- METADATA_INSTANCE_DELETE
- METADATA_INSTANCE_UPDATE
- METADATA_TEMPLATE_CREATE
- METADATA_TEMPLATE_DELETE
- METADATA_TEMPLATE_UPDATE
- MOVE
- NEW_USER
- PREVIEW
- REMOVE_DEVICE_ASSOCIATION
- REMOVE_LOGIN_ACTIVITY_DEVICE
- RENAME
- RETENTION_POLICY_ASSIGNMENT_ADD
- SHARE
- SHARE_EXPIRATION
- SHIELD_ALERT
- SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED
- SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED_MISSING_JUSTIFICATION
- SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED
- SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED_MISSING_JUSTIFICATION
- SHIELD_JUSTIFICATION_APPROVAL
- SIGN_DOCUMENT_ASSIGNED
- SIGN_DOCUMENT_CANCELLED
- SIGN_DOCUMENT_COMPLETED
- SIGN_DOCUMENT_CONVERTED
- SIGN_DOCUMENT_CREATED
- SIGN_DOCUMENT_DECLINED
- SIGN_DOCUMENT_EXPIRED
- SIGN_DOCUMENT_SIGNED
- SIGN_DOCUMENT_VIEWED_BY_SIGNED
- SIGNER_DOWNLOADED
- SIGNER_FORWARDED
- STORAGE_EXPIRATION
- TAG_ITEM_CREATE
- TASK_ASSIGNMENT_CREATE
- TASK_ASSIGNMENT_DELETE
- TASK_ASSIGNMENT_UPDATE
- TASK_CREATE
- TASK_UPDATE
- TERMS_OF_SERVICE_ACCEPT
- TERMS_OF_SERVICE_REJECT
- UNDELETE
- UNLOCK
- UNSHARE
- UPDATE_COLLABORATION_EXPIRATION
- UPDATE_SHARE_EXPIRATION
- UPLOAD
- USER_AUTHENTICATE_OAUTH2_ACCESS_TOKEN_CREATE
- WATERMARK_LABEL_CREATE
- WATERMARK_LABEL_DELETE
example: FILE_MARKED_MALICIOUS
title: Event Type
type: string
- description: The event type that triggered this event
recorded_at:
description: When the event object was recorded in database
example: 2022-12-12T10:54:43-08:00
format: date-time
type: string
session_id:
description: |-
The session of the user that performed the action. Not all events will
populate this attribute.
example: 70090280850c8d2a1933c1
type: string
source:
allOf:
- oneOf:
- $ref: "#/components/schemas/User"
- $ref: "#/components/schemas/EventSource"
- $ref: "#/components/schemas/File"
- $ref: "#/components/schemas/Folder"
- description: |-
The resource that triggered this event. For more information,
check out the guide on event triggers.
type:
description: "`event`"
example: event
type: string
title: Event
type: object
x-box-resource-id: event
x-box-tag: events
EventSource:
description: |-
The source file or folder that triggered an event in
the event stream.
properties:
classification:
description: |-
The object containing classification information for the item that
triggered the event. This field will not appear if the item does not
have a classification set.
properties:
name:
description: The classification's name
example: Top Secret
type: string
type: object
item_id:
description: |
The unique identifier that represents the
item.
example: "560284318361"
nullable: false
type: string
item_name:
description: |
The name of the item.
example: report.pdf
nullable: false
type: string
item_type:
description: |
The type of the item that the event
represents. Can be `file` or `folder`.
enum:
- file
- folder
example: file
nullable: false
type: string
owned_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who owns this item.
- nullable: false
parent:
allOf:
- $ref: "#/components/schemas/Folder--Mini"
- description: |-
The optional folder that this folder is located within.
This value may be `null` for some folders such as the
root folder or the trash folder.
nullable: true
required:
- item_type
- item_id
- item_name
title: Event source
type: object
x-box-resource-id: event_source
Events:
description: A list of event objects
properties:
chunk_size:
description: The number of events returned in this response.
example: 2
format: int64
type: integer
entries:
items:
$ref: "#/components/schemas/Event"
type: array
next_stream_position:
description: |-
The stream position of the start of the next page (chunk)
of events.
example: "1152922976252290886"
type: string
title: Events
type: object
x-box-resource-id: events
x-box-tag: events
File:
allOf:
- $ref: "#/components/schemas/File--Mini"
- properties:
content_created_at:
description: |-
The date and time at which this file was originally
created, which might be before it was uploaded to Box.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
content_modified_at:
description: |-
The date and time at which this file was last updated,
which might be before it was uploaded to Box.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
created_at:
description: The date and time when the file was created on Box.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: false
type: string
created_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who created this file
description:
description: The optional description of this file
example: Contract for Q1 renewal
maxLength: 256
nullable: false
type: string
item_status:
description: |-
Defines if this item has been deleted or not.
* `active` when the item has is not in the trash
* `trashed` when the item has been moved to the trash but not deleted
* `deleted` when the item has been permanently deleted.
enum:
- active
- trashed
- deleted
example: active
nullable: false
type: string
modified_at:
description: The date and time when the file was last updated on Box.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: false
type: string
modified_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who last modified this file
- nullable: false
owned_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who owns this file
- nullable: false
parent:
allOf:
- $ref: "#/components/schemas/Folder--Mini"
- description: The folder that this file is located within.
nullable: true
path_collection:
allOf:
- description: A list of parent folders for an item.
properties:
entries:
description: The parent folders for this item
items:
$ref: "#/components/schemas/Folder--Mini"
nullable: false
type: array
total_count:
description: The number of folders in this list.
example: 1
format: int64
nullable: false
type: integer
required:
- total_count
- entries
title: Path collection
type: object
- description: |-
The tree of folders that this file is contained in,
starting at the root.
- nullable: false
purged_at:
description: |-
The time at which this file is expected to be purged
from the trash.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
shared_link:
allOf:
- description: |-
Shared links provide direct, read-only access to files or folder on Box.
Shared links with open access level allow anyone with the URL
to access the item, while shared links with company or collaborators access
levels can only be accessed by appropriately authenticated Box users.
properties:
access:
description: |-
The access level for this shared link.
* `open` - provides access to this item to anyone with this link
* `company` - only provides access to this item to people the same company
* `collaborators` - only provides access to this item to people who are
collaborators on this item
If this field is omitted when creating the shared link, the access level
will be set to the default access level specified by the enterprise admin.
enum:
- open
- company
- collaborators
example: open
nullable: false
type: string
download_count:
description: The number of times this item has been downloaded.
example: 3
nullable: false
type: integer
download_url:
description: |-
A URL that can be used to download the file. This URL can be used in
a browser to download the file. This URL includes the file
extension so that the file will be saved with the right file type.
This property will be `null` for folders.
example: https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg
format: url
nullable: true
type: string
x-box-premium-feature: true
effective_access:
description: |-
The effective access level for the shared link. This can be a more
restrictive access level than the value in the `access` field when the
enterprise settings restrict the allowed access levels.
enum:
- open
- company
- collaborators
example: company
nullable: false
type: string
effective_permission:
description: |-
The effective permissions for this shared link.
These result in the more restrictive combination of
the share link permissions and the item permissions set
by the administrator, the owner, and any ancestor item
such as a folder.
enum:
- can_edit
- can_download
- can_preview
- no_access
example: can_download
nullable: false
type: string
is_password_enabled:
description: Defines if the shared link requires a password to access the item.
example: true
nullable: false
type: boolean
permissions:
description: |-
Defines if this link allows a user to preview, edit, and download an item.
These permissions refer to the shared link only and
do not supersede permissions applied to the item itself.
properties:
can_download:
description: |-
Defines if the shared link allows for the item to be downloaded. For
shared links on folders, this also applies to any items in the folder.
This value can be set to `true` when the effective access level is
set to `open` or `company`, not `collaborators`.
example: true
nullable: false
type: boolean
can_edit:
description: |-
Defines if the shared link allows for the item to be edited.
This value can only be `true` if `can_download` is also `true` and if
the item has a type of `file`.
example: false
nullable: false
type: boolean
can_preview:
description: |-
Defines if the shared link allows for the item to be previewed.
This value is always `true`. For shared links on folders this also
applies to any items in the folder.
example: true
nullable: false
type: boolean
required:
- can_download
- can_preview
- can_edit
type: object
preview_count:
description: The number of times this item has been previewed.
example: 3
nullable: false
type: integer
unshared_at:
description: |-
The date and time when this link will be unshared. This field can only be
set by users with paid accounts.
example: 2018-04-13T13:53:23-07:00
format: date-time
nullable: true
type: string
url:
description: |-
The URL that can be used to access the item on Box.
This URL will display the item in Box's preview UI where the file
can be downloaded if allowed.
This URL will continue to work even when a custom `vanity_url`
has been set for this shared link.
example: https://www.box.com/s/vspke7y05sb214wjokpk
format: url
nullable: false
type: string
vanity_name:
description: The custom name of a shared link, as used in the `vanity_url` field.
example: my_url
nullable: true
type: string
vanity_url:
description: |-
The "Custom URL" that can also be used to preview the item on Box. Custom
URLs can only be created or modified in the Box Web application.
example: https://acme.app.box.com/v/my_url/
format: url
nullable: true
type: string
required:
- url
- accessed
- effective_access
- effective_permission
- is_password_enabled
- download_count
- preview_count
title: Shared link
type: object
- description: |-
The shared link for this file. This will be
`null` if no shared link has been created for this
file.
- nullable: true
size:
description: |-
The file size in bytes. Be careful parsing this integer as it can
get very large and cause an integer overflow.
example: 629644
nullable: false
type: integer
trashed_at:
description: The time at which this file was put in the trash.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
description: |-
A standard representation of a file, as returned from any
file API endpoints by default
required:
- description
- size
- path_collection
- created_at
- modified_at
- modified_by
- owned_by
- item_status
title: File
type: object
x-box-resource-id: file
x-box-variant: standard
File--Base:
description: |-
The bare basic representation of a file, the minimal
amount of fields returned when using the `fields` query
parameter.
properties:
etag:
description: |-
The HTTP `etag` of this file. This can be used within some API
endpoints in the `If-Match` and `If-None-Match` headers to only
perform changes on the file if (no) changes have happened.
example: "1"
nullable: true
type: string
id:
description: |-
The unique identifier that represent a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "12345"
nullable: false
type: string
type:
description: "`file`"
enum:
- file
example: file
nullable: false
type: string
required:
- id
- type
title: File (Base)
type: object
x-box-resource-id: file--base
x-box-sanitized: true
x-box-tag: files
x-box-variant: base
x-box-variants:
- base
- mini
- standard
- full
File--Full:
allOf:
- $ref: "#/components/schemas/File"
- properties:
allowed_invitee_roles:
description: |-
A list of the types of roles that user can be invited at
when sharing this file.
example:
- editor
items:
enum:
- editor
- viewer
- previewer
- uploader
- previewer uploader
- viewer uploader
- co-owner
type: string
nullable: false
type: array
classification:
allOf:
- description: The classification applied to an item
properties:
color:
description: |-
The color that is used to display the
classification label in a user-interface. Colors are defined by the admin
or co-admin who created the classification in the Box web app.
example: "#FF0000"
type: string
definition:
description: An explanation of the meaning of this classification.
example: Content that should not be shared outside the company.
type: string
name:
description: The name of the classification
example: Top Secret
type: string
type: object
- description: Details about the classification applied to this file.
- nullable: true
comment_count:
description: The number of comments on this file
example: 10
type: integer
disposition_at:
description: The retention expiration timestamp for the given file
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
expires_at:
description: When the file will automatically be deleted
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
expiring_embed_link:
allOf:
- allOf:
- description: The basics of an access token
properties:
access_token:
description: The requested access token.
example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ
format: token
type: string
expires_in:
description: The time in seconds in seconds by which this token will expire.
example: 3600
format: int64
type: integer
restricted_to:
description: |-
The permissions that this access token permits,
providing a list of resources (files, folders, etc)
and the scopes permitted for each of those resources.
items:
$ref: "#/components/schemas/FileScope"
type: array
token_type:
description: The type of access token returned.
enum:
- bearer
example: bearer
type: string
type: object
- properties:
url:
description: |-
The actual expiring embed URL for this file, constructed
from the file ID and access tokens specified in this object.
example: https://cloud.app.box.com/preview/expiring_embed/...
format: url
type: string
description: An expiring Box Embed Link.
title: Expiring embed link
type: object
- description: |-
Requesting this field creates an expiring Box Embed URL for an
embedded preview session in an `iframe`.
This URL will expire after 60 seconds and the session will
expire after 60 minutes.
Not all file types are supported for these embed URLs. Box Embed
is not optimized for mobile browsers and should not be used in web
experiences designed for mobile devices. Many UI elements, like
the **download** and **print** options might not show in mobile
browsers.
extension:
description: |-
Indicates the (optional) file extension for this file. By default,
this is set to an empty string.
example: pdf
type: string
has_collaborations:
description: Specifies if this file has any other collaborators.
example: true
nullable: false
type: boolean
is_accessible_via_shared_link:
description: |-
Specifies if the file can be accessed
via the direct shared link or a shared link
to a parent folder.
enum:
- true
- false
example: true
type: boolean
is_externally_owned:
description: |-
Specifies if this file is owned by a user outside of the
authenticated enterprise.
example: true
nullable: false
type: boolean
is_package:
description: |-
Indicates if the file is a package. Packages are commonly used
by Mac Applications and can include iWork files.
example: true
type: boolean
lock:
allOf:
- description: |-
The lock held on a file. A lock prevents a file from being moved,
renamed, or otherwise changed by anyone else than the user who created the
lock.
properties:
app_type:
description: |-
If the lock is managed by an application rather than a user, this
field identifies the type of the application that holds the lock.
This is an open enum and may be extended with additional values in
the future.
enum:
- gsuite
- office_wopi
- office_wopiplus
- other
example: office_wopiplus
nullable: true
type: string
created_at:
description: The time this lock was created at.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
created_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who created the lock.
expired_at:
description: The time this lock is to expire at, which might be in the past.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
id:
description: The unique identifier for this lock
example: "11446498"
type: string
is_download_prevented:
description: Whether or not the file can be downloaded while locked.
example: true
type: boolean
type:
description: "`lock`"
enum:
- lock
example: lock
type: string
title: Lock
type: object
- description: |-
The lock held on this file. If there is no lock, this can either
be `null` or have a timestamp in the past.
nullable: true
metadata:
allOf:
- additionalProperties:
additionalProperties:
$ref: "#/components/schemas/Metadata"
description: |-
A list of metadata instances, nested within key-value pairs of their `scope`
and `templateKey`.
example:
marketingCollateral:
$canEdit: true
$id: 01234500-12f1-1234-aa12-b1d234cb567e
$parent: folder_59449484661
$scope: enterprise_27335
$template: marketingCollateral
$type: properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0
$typeVersion: 2
$version: 1
type: object
description: |-
A list of metadata instances, nested within key-value pairs of their `scope`
and `templateKey`.
To access the metadata for a file or folder, first use the
metadata endpoints to determine the metadata templates available to your
enterprise.
Then use the `GET /files/:id` or `GET /folder/:id`
endpoint with the `fields` query parameter to get
the metadata by ID.
To request a metadata instance for a particular `scope` and `templateKey`
use the following format for the `fields` parameter:
`metadata..`
For example, `?fields=metadata.enterprise_27335.marketingCollateral`.
example:
enterprise_27335:
marketingCollateral:
$canEdit: true
$id: 01234500-12f1-1234-aa12-b1d234cb567e
$parent: folder_59449484661
$scope: enterprise_27335
$template: marketingCollateral
$type: properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0
$typeVersion: 2
$version: 1
title: Item metadata instances
type: object
- description: |-
An object containing the metadata instances that have been
attached to this file.
Each metadata instance is uniquely identified by its `scope` and
`templateKey`. There can only be one instance of any metadata
template attached to each file. Each metadata instance is nested
within an object with the `templateKey` as the key, which again
itself is nested in an object with the `scope` as the key.
permissions:
allOf:
- allOf:
- description: The permissions that the authenticated user has for an item.
properties:
can_delete:
description: Specifies if the current user can delete this item.
example: true
nullable: false
type: boolean
can_download:
description: Specifies if the current user can download this item.
example: true
nullable: false
type: boolean
can_invite_collaborator:
description: |-
Specifies if the current user can invite new
users to collaborate on this item, and if the user can
update the role of a user already collaborated on this
item.
example: true
nullable: false
type: boolean
can_rename:
description: Specifies if the user can rename this item.
example: true
nullable: false
type: boolean
can_set_share_access:
description: |-
Specifies if the user can change the access level of an
existing shared link on this item.
example: true
nullable: false
type: boolean
can_share:
description: Specifies if the user can create a shared link for this item.
example: true
nullable: false
type: boolean
required:
- can_delete
- can_download
- can_invite_collaborator
- can_rename
- can_set_share_access
- can_share
type: object
- properties:
can_annotate:
description: Specifies if the user can place annotations on this file.
example: true
nullable: false
type: boolean
can_comment:
description: Specifies if the user can place comments on this file.
example: true
nullable: false
type: boolean
can_preview:
description: Specifies if the user can preview this file.
example: true
nullable: false
type: boolean
can_upload:
description: Specifies if the user can upload a new version of this file.
example: true
nullable: false
type: boolean
can_view_annotations_all:
description: Specifies if the user view all annotations placed on this file
example: true
nullable: false
type: boolean
can_view_annotations_self:
description: |-
Specifies if the user view annotations placed by themselves
on this file
example: true
nullable: false
type: boolean
description: The permissions that the authenticated user has for a file.
required:
- can_annotate
- can_comment
- can_preview
- can_upload
- can_view_annotations_all
- can_view_annotations_self
type: object
- description: |-
Describes the permissions that the current user has
for this file.
- nullable: false
representations:
allOf:
- description: A list of file representations
properties:
entries:
description: A list of files
items:
description: A file representation
properties:
content:
description: |-
An object containing the URL that can be used to actually fetch
the representation.
properties:
url_template:
description: |-
The download URL that can be used to fetch the representation.
Make sure to make an authenticated API call to this endpoint.
This URL is a template and will require the `{+asset_path}` to
be replaced by a path. In general, for unpaged representations
it can be replaced by an empty string.
For paged representations, replace the `{+asset_path}` with the
page to request plus the extension for the file, for example
`1.pdf`.
When requesting the download URL the following additional
query params can be passed along.
* `set_content_disposition_type` - Sets the
`Content-Disposition` header in the API response with the
specified disposition type of either `inline` or `attachment`.
If not supplied, the `Content-Disposition` header is not
included in the response.
* `set_content_disposition_filename` - Allows the application to
define the representation's file name used in the
`Content-Disposition` header. If not defined, the filename
is derived from the source file name in Box combined with the
extension of the representation.
example: https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567
type: string
type: object
info:
description: |-
An object containing the URL that can be used to fetch more info
on this representation.
properties:
url:
description: |-
The API URL that can be used to get more info on this file
representation. Make sure to make an authenticated API call
to this endpoint.
example: https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048
type: string
type: object
properties:
description: An object containing the size and type of this presentation.
properties:
dimensions:
description: The width by height size of this representation in pixels.
example: 2048x2048
format: x
type: string
paged:
description: |-
Indicates if the representation is build up out of multiple
pages.
example: true
type: boolean
thumb:
description: |-
Indicates if the representation can be used as a thumbnail of
the file.
example: true
type: boolean
type: object
representation:
description: Indicates the file type of the returned representation.
example: png
type: string
status:
description: An object containing the status of this representation.
properties:
state:
description: |-
The status of the representation.
* `success` defines the representation as ready to be viewed.
* `viewable` defines a video to be ready for viewing.
* `pending` defines the representation as to be generated. Retry
this endpoint to re-check the status.
* `none` defines that the representation will be created when
requested. Request the URL defined in the `info` object to
trigger this generation.
enum:
- success
- viewable
- pending
- none
example: success
type: string
type: object
type: object
type: array
title: Representations
type: object
- description: |-
A list of representations for a file that can be used to
display a placeholder of the file in your application. By default
this returns all representations and we recommend using the
`x-rep-hints` header to further customize the desired
representations.
shared_link_permission_options:
description: |-
A list of the types of roles that user can be invited at
when sharing this file.
example:
- can_preview
items:
enum:
- can_preview
- can_download
- can_edit
type: string
nullable: true
type: array
tags:
allOf:
- description: |-
The tags for this item. These tags are shown in
the Box web app and mobile apps next to an item.
To add or remove a tag, retrieve the item's current tags,
modify them, and then update this field.
There is a limit of 100 tags per item, and 10,000
unique tags per enterprise.
example:
- approved
items:
type: string
maxItems: 100
minItems: 1
type: array
- nullable: false
uploader_display_name:
allOf:
- description: |-
The display name of the user that uploaded the file. In most cases this is the
name of the user logged in at the time of the upload.
If the file was uploaded using a File Request form that requires the user to
provide an email address, this field is populated with that email address. If
an email address was not required in the File Request form, this field is set
to return a value of `File Request`.
In all other anonymous cases where no email was provided this field
will default to a value of `Someone`.
example: Ellis Wiggins
nullable: false
title: Uploader display name
type: string
version_number:
description: The version number of this file
example: "1"
type: string
watermark_info:
allOf:
- description: Details about the watermark applied to this item
properties:
is_watermarked:
description: Specifies if this item has a watermark applied.
example: true
nullable: false
type: boolean
type: object
- description: Details about the watermark applied to this file
description: |-
A full representation of a file, as can be returned from any
file API endpoints by default
title: File (Full)
type: object
x-box-resource-id: file--full
x-box-variant: full
File--Mini:
allOf:
- $ref: "#/components/schemas/File--Base"
- properties:
file_version:
allOf:
- $ref: "#/components/schemas/FileVersion--Mini"
- description: The information about the current version of the file.
name:
description: The name of the file
example: Contract.pdf
type: string
sequence_id:
allOf:
- description: |-
A numeric identifier that represents the most recent user event
that has been applied to this item.
This can be used in combination with the `GET /events`-endpoint
to filter out user events that would have occurred before this
identifier was read.
An example would be where a Box Drive-like application
would fetch an item via the API, and then listen to incoming
user events for changes to the item. The application would
ignore any user events where the `sequence_id` in the event
is smaller than or equal to the `sequence_id` in the originally
fetched resource.
example: "3"
nullable: false
type: string
- nullable: false
sha1:
description: |-
The SHA1 hash of the file. This can be used to compare the contents
of a file on Box with a local file.
example: 85136C79CBF9FE36BB9D05D0639C70C265C18D37
format: digest
nullable: false
type: string
description: |-
A mini representation of a file, used when
nested under another resource.
required:
- sequence_id
- sha1
title: File (Mini)
type: object
x-box-resource-id: file--mini
x-box-variant: mini
FileConflict:
allOf:
- $ref: "#/components/schemas/File--Mini"
- properties:
file_version:
$ref: "#/components/schemas/FileVersion--Mini"
sha1:
description: The SHA1 hash of the file.
example: 85136C79CBF9FE36BB9D05D0639C70C265C18D37
type: string
description: A representation of a file that is used to show
title: File (Conflict)
type: object
x-box-resource-id: file_conflict
x-box-sanitized: true
x-box-tag: null
FileRequest:
description: |-
A standard representation of a file request, as returned
from any file request API endpoints by default.
properties:
created_at:
description: The date and time when the file request was created.
example: 2020-09-28T10:53:43-08:00
format: date-time
nullable: false
type: string
created_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who created this file request.
description:
description: |-
The optional description of this file request. This is
shown in the Box UI to users uploading files.
This defaults to description of the file request that was
copied to create this file request.
example: Following documents are requested for your process
nullable: true
type: string
etag:
description: |-
The HTTP `etag` of this file. This can be used in combination with
the `If-Match` header when updating a file request. By providing that
header, a change will only be performed on the file request if the `etag`
on the file request still matches the `etag` provided in the `If-Match`
header.
example: "1"
nullable: true
type: string
expires_at:
description: |-
The date after which a file request will no longer accept new
submissions.
After this date, the `status` will automatically be set to
`inactive`.
example: 2020-09-28T10:53:43-08:00
format: date-time
type: string
folder:
allOf:
- $ref: "#/components/schemas/Folder--Mini"
- description: |-
The folder that this file request is associated with.
Files submitted through the file request form will be
uploaded to this folder.
nullable: false
id:
description: The unique identifier for this file request.
example: "42037322"
readOnly: true
type: string
is_description_required:
description: |-
Whether a file request submitter is required to provide
a description of the files they are submitting.
When this setting is set to true, the Box UI will show
a description field on the file request form.
This defaults to setting of file request that was
copied to create this file request.
example: true
type: boolean
is_email_required:
description: |-
Whether a file request submitter is required to provide
their email address.
When this setting is set to true, the Box UI will show
an email field on the file request form.
This defaults to setting of file request that was
copied to create this file request.
example: true
type: boolean
status:
description: |-
The status of the file request. This defaults
to `active`.
When the status is set to `inactive`, the file request
will no longer accept new submissions, and any visitor
to the file request URL will receive a `HTTP 404` status
code.
This defaults to status of file request that was
copied to create this file request.
enum:
- active
- inactive
example: active
type: string
title:
description: |-
The title of file request. This is shown
in the Box UI to users uploading files.
This defaults to title of the file request that was
copied to create this file request.
example: Please upload documents
type: string
type:
description: "`file_request`"
enum:
- file_request
example: file_request
readOnly: true
type: string
updated_at:
description: The date and time when the file request was last updated.
example: 2020-09-28T10:53:43-08:00
format: date-time
nullable: false
type: string
updated_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who last modified this file request.
- nullable: false
url:
description: |-
The generated URL for this file request. This URL can be shared
with users to let them upload files to the associated folder.
example: /f/19e57f40ace247278a8e3d336678c64a
readOnly: true
type: string
required:
- folder
- created_at
- updated_at
title: File Request
type: object
x-box-resource-id: file_request
x-box-tag: file_requests
FileRequestCopyRequest:
allOf:
- $ref: "#/components/schemas/FileRequestUpdateRequest"
- properties:
folder:
description: The folder to associate the new file request to.
properties:
id:
description: |-
The ID of the folder to associate the new
file request to.
example: "42037322"
type: string
type:
description: "`folder`"
enum:
- folder
example: folder
type: string
required:
- id
type: object
description: The request body to copy a file request.
required:
- folder
title: File Request (Copy)
type: object
FileRequestUpdateRequest:
description: The request body to update a file request.
properties:
description:
description: |-
An optional new description for the file request. This can be
used to change the description of the file request.
This will default to the value on the existing file request.
example: Please upload required documents
type: string
expires_at:
description: |-
The date after which a file request will no longer accept new
submissions.
After this date, the `status` will automatically be set to
`inactive`.
This will default to the value on the existing file request.
example: 2020-09-28T10:53:43-08:00
format: date-time
type: string
is_description_required:
description: |-
Whether a file request submitter is required to provide
a description of the files they are submitting.
When this setting is set to true, the Box UI will show
a description field on the file request form.
This will default to the value on the existing file request.
example: true
type: boolean
is_email_required:
description: |-
Whether a file request submitter is required to provide
their email address.
When this setting is set to true, the Box UI will show
an email field on the file request form.
This will default to the value on the existing file request.
example: true
type: boolean
status:
description: |-
An optional new status of the file request.
When the status is set to `inactive`, the file request
will no longer accept new submissions, and any visitor
to the file request URL will receive a `HTTP 404` status
code.
This will default to the value on the existing file request.
enum:
- active
- inactive
example: active
type: string
title:
description: |-
An optional new title for the file request. This can be
used to change the title of the file request.
This will default to the value on the existing file request.
example: Please upload required documents
type: string
title: File Request (Update)
type: object
FileScope:
description: A relation between a file and the scopes for which the file can be accessed
properties:
object:
allOf:
- $ref: "#/components/schemas/File--Mini"
- description: The file for which the file can be accessed
scope:
description: The file scopes for the file access
enum:
- annotation_edit
- annotation_view_all
- annotation_view_self
- base_explorer
- base_picker
- base_preview
- base_upload
- item_delete
- item_download
- item_preview
- item_rename
- item_share
example: item_download
type: string
title: File scope
type: object
FileVersion:
allOf:
- $ref: "#/components/schemas/FileVersion--Mini"
- properties:
created_at:
description: When the file version object was created
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
modified_at:
description: When the file version object was last updated
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
modified_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who last updated the file version
name:
description: The name of the file version
example: tigers.jpeg
type: string
purged_at:
description: When the file version object will be permanently deleted.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
restored_at:
description: When the file version was restored from the trash.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
restored_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who restored the file version from the trash.
size:
description: Size of the file version in bytes
example: 629644
format: int64
type: integer
trashed_at:
description: When the file version object was trashed.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
trashed_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who trashed the file version
uploader_display_name:
allOf:
- description: |-
The display name of the user that uploaded the file. In most cases this is the
name of the user logged in at the time of the upload.
If the file was uploaded using a File Request form that requires the user to
provide an email address, this field is populated with that email address. If
an email address was not required in the File Request form, this field is set
to return a value of `File Request`.
In all other anonymous cases where no email was provided this field
will default to a value of `Someone`.
example: Ellis Wiggins
nullable: false
title: Uploader display name
type: string
description: A standard representation of a file version
title: File version
type: object
x-box-resource-id: file_version
x-box-variant: standard
FileVersion--Base:
description: |-
The bare basic representation of a file version, the minimal
amount of fields returned when using the `fields` query
parameter.
properties:
id:
description: The unique identifier that represent a file version.
example: "12345"
nullable: false
type: string
type:
description: "`file_version`"
enum:
- file_version
example: file_version
nullable: false
type: string
required:
- id
- type
title: File version (Base)
type: object
x-box-resource-id: file_version--base
x-box-sanitized: true
x-box-variant: base
x-box-variants:
- base
- mini
- standard
- full
FileVersion--Full:
allOf:
- $ref: "#/components/schemas/FileVersion"
- properties:
version_number:
description: The version number of this file version
example: "1"
type: string
description: |-
A full representation of a file version, as can be returned from any
file version API endpoints by default
title: File version (Full)
type: object
x-box-resource-id: file_version--full
x-box-variant: full
FileVersion--Mini:
allOf:
- $ref: "#/components/schemas/FileVersion--Base"
- properties:
sha1:
description: The SHA1 hash of this version of the file.
example: 134b65991ed521fcfe4724b7d814ab8ded5185dc
type: string
description: |-
A mini representation of a file version, used when
nested within another resource.
title: File version (Mini)
type: object
x-box-resource-id: file_version--mini
x-box-variant: mini
FileVersionLegalHold:
description: |-
File-Version-Legal-Hold is an entity representing all
holds on a File Version.
properties:
deleted_at:
description: |-
Time that this File-Version-Legal-Hold was
deleted.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
file:
allOf:
- $ref: "#/components/schemas/File--Mini"
- description: |-
The file for the file version held.
Note that there is no guarantee that the current
version of this file is held.
file_version:
allOf:
- $ref: "#/components/schemas/FileVersion--Mini"
- description: The file version that is held
id:
description: The unique identifier for this file version legal hold
example: "11446498"
type: string
legal_hold_policy_assignments:
description: List of assignments contributing to this Hold.
items:
$ref: "#/components/schemas/LegalHoldPolicyAssignment"
type: array
type:
description: "`file_version_legal_hold`"
enum:
- file_version_legal_hold
example: file_version_legal_hold
type: string
title: File version legal hold
type: object
x-box-resource-id: file_version_legal_hold
x-box-tag: file_version_legal_holds
FileVersionLegalHolds:
allOf:
- description: |-
The part of an API response that describes marker
based pagination
properties:
limit:
description: |-
The limit that was used for these entries. This will be the same as the
`limit` query parameter unless that value exceeded the maximum value
allowed. The maximum value varies by API.
example: 1000
format: int64
type: integer
next_marker:
description: The marker for the start of the next page of results.
example: 3000
format: int64
type: integer
prev_marker:
description: The marker for the start of the previous page of results.
example: 1000
format: int64
type: integer
type: object
- properties:
entries:
items:
$ref: "#/components/schemas/FileVersionLegalHold"
type: array
description: A list of file version legal holds.
title: File version legal holds
type: object
x-box-resource-id: file_version_legal_holds
x-box-tag: file_version_legal_holds
FileVersionRetention:
description: |-
A retention policy blocks permanent deletion of content
for a specified amount of time. Admins can apply policies to
specified folders, or an entire enterprise. A file version retention
is a record for a retained file version. To use this feature,
you must have the manage retention policies scope enabled for your
API key via your application management console. For more information
about retention policies, please visit our help documentation
properties:
applied_at:
description: |-
When this file version retention object was
created
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
disposition_at:
description: |-
When the retention expires on this file
version retention
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
file:
allOf:
- $ref: "#/components/schemas/File--Mini"
- description: The file this file version retention was applied to
file_version:
allOf:
- $ref: "#/components/schemas/FileVersion--Mini"
- description: |-
The file version this file version retention was
applied to
id:
description: The unique identifier for this file version retention.
example: "11446498"
type: string
type:
description: "`file_version_retention`"
enum:
- file_version_retention
example: file_version_retention
type: string
winning_retention_policy:
allOf:
- $ref: "#/components/schemas/RetentionPolicy--Mini"
- description: |-
The winning retention policy applied to this file
version retention. A file version can have multiple
retention policies applied.
title: File version retention
type: object
x-box-resource-id: file_version_retention
x-box-tag: file_version_retentions
FileVersionRetentions:
allOf:
- description: |-
The part of an API response that describes marker
based pagination
properties:
limit:
description: |-
The limit that was used for these entries. This will be the same as the
`limit` query parameter unless that value exceeded the maximum value
allowed. The maximum value varies by API.
example: 1000
format: int64
type: integer
next_marker:
description: The marker for the start of the next page of results.
example: 3000
format: int64
type: integer
prev_marker:
description: The marker for the start of the previous page of results.
example: 1000
format: int64
type: integer
type: object
- properties:
entries:
items:
$ref: "#/components/schemas/FileVersionRetention"
type: array
description: A list of file version retentions.
title: File version retentions
type: object
x-box-resource-id: file_version_retentions
x-box-tag: file_version_retentions
FileVersions:
allOf:
- description: The part of an API response that describes pagination
properties:
limit:
description: |-
The limit that was used for these entries. This will be the same as the
`limit` query parameter unless that value exceeded the maximum value
allowed. The maximum value varies by API.
example: 1000
format: int64
type: integer
offset:
description: |-
The 0-based offset of the first entry in this set. This will be the same
as the `offset` query parameter.
This field is only returned for calls that use offset-based pagination.
For marker-based paginated APIs, this field will be omitted.
example: 2000
format: int64
type: integer
order:
description: |-
The order by which items are returned.
This field is only returned for calls that use offset-based pagination.
For marker-based paginated APIs, this field will be omitted.
items:
description: The order in which a pagination is ordered
properties:
by:
description: The field to order by
example: type
type: string
direction:
description: The direction to order by, either ascending or descending
enum:
- ASC
- DESC
example: ASC
type: string
type: object
type: array
total_count:
description: |-
One greater than the offset of the last entry in the entire collection.
The total number of entries in the collection may be less than
`total_count`.
This field is only returned for calls that use offset-based pagination.
For marker-based paginated APIs, this field will be omitted.
example: 5000
format: int64
type: integer
type: object
- properties:
entries:
items:
$ref: "#/components/schemas/FileVersion"
type: array
description: A list of file versions
title: File versions
type: object
x-box-resource-id: file_versions
x-box-tag: file_versions
Files:
description: A list of files
properties:
entries:
description: A list of files
items:
$ref: "#/components/schemas/File"
type: array
total_count:
description: The number of files.
example: 1
format: int64
type: integer
title: Files
type: object
x-box-resource-id: files
x-box-tag: files
FilesUnderRetention:
allOf:
- description: |-
The part of an API response that describes marker
based pagination
properties:
limit:
description: |-
The limit that was used for these entries. This will be the same as the
`limit` query parameter unless that value exceeded the maximum value
allowed. The maximum value varies by API.
example: 1000
format: int64
type: integer
next_marker:
description: The marker for the start of the next page of results.
example: 3000
format: int64
type: integer
prev_marker:
description: The marker for the start of the previous page of results.
example: 1000
format: int64
type: integer
type: object
- properties:
entries:
items:
$ref: "#/components/schemas/File--Mini"
type: array
description: A list of files under retention.
title: Files under retention
type: object
x-box-resource-id: files_under_retention
x-box-tag: retention_policy_assignments
Folder:
allOf:
- $ref: "#/components/schemas/Folder--Mini"
- properties:
content_created_at:
description: |-
The date and time at which this folder was originally
created.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
content_modified_at:
description: The date and time at which this folder was last updated.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
created_at:
description: |-
The date and time when the folder was created. This value may
be `null` for some folders such as the root folder or the trash
folder.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
created_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who created this folder
- nullable: false
description:
allOf:
- description: The optional description of this folder
example: Legal contracts for the new ACME deal
maxLength: 256
nullable: false
type: string
- nullable: false
folder_upload_email:
nullable: true
properties:
access:
description: |-
When this parameter has been set, users can email files
to the email address that has been automatically
created for this folder.
To create an email address, set this property either when
creating or updating the folder.
When set to `collaborators`, only emails from registered email
addresses for collaborators will be accepted. This includes
any email aliases a user might have registered.
When set to `open` it will accept emails from any email
address.
enum:
- open
- collaborators
example: open
nullable: false
type: string
email:
description: The optional upload email address for this folder.
example: upload.Contracts.asd7asd@u.box.com
format: email
nullable: false
type: string
type: object
item_collection:
allOf:
- $ref: "#/components/schemas/Items"
- description: |-
A page of the items that are in the folder.
This field can only be requested when querying a folder's
information, not when querying a folder's items.
- nullable: false
item_status:
description: |-
Defines if this item has been deleted or not.
* `active` when the item has is not in the trash
* `trashed` when the item has been moved to the trash but not deleted
* `deleted` when the item has been permanently deleted.
enum:
- active
- trashed
- deleted
example: active
nullable: false
type: string
modified_at:
description: |-
The date and time when the folder was last updated. This value may
be `null` for some folders such as the root folder or the trash
folder.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
modified_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who last modified this folder.
- nullable: false
owned_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who owns this folder.
- nullable: false
parent:
allOf:
- $ref: "#/components/schemas/Folder--Mini"
- description: |-
The optional folder that this folder is located within.
This value may be `null` for some folders such as the
root folder or the trash folder.
nullable: true
path_collection:
allOf:
- description: A list of parent folders for an item.
properties:
entries:
description: The parent folders for this item
items:
$ref: "#/components/schemas/Folder--Mini"
nullable: false
type: array
total_count:
description: The number of folders in this list.
example: 1
format: int64
nullable: false
type: integer
required:
- total_count
- entries
title: Path collection
type: object
- description: |-
The tree of folders that this folder is contained in,
starting at the root.
- nullable: false
purged_at:
description: |-
The time at which this folder is expected to be purged
from the trash.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
shared_link:
allOf:
- description: |-
Shared links provide direct, read-only access to files or folder on Box.
Shared links with open access level allow anyone with the URL
to access the item, while shared links with company or collaborators access
levels can only be accessed by appropriately authenticated Box users.
properties:
access:
description: |-
The access level for this shared link.
* `open` - provides access to this item to anyone with this link
* `company` - only provides access to this item to people the same company
* `collaborators` - only provides access to this item to people who are
collaborators on this item
If this field is omitted when creating the shared link, the access level
will be set to the default access level specified by the enterprise admin.
enum:
- open
- company
- collaborators
example: open
nullable: false
type: string
download_count:
description: The number of times this item has been downloaded.
example: 3
nullable: false
type: integer
download_url:
description: |-
A URL that can be used to download the file. This URL can be used in
a browser to download the file. This URL includes the file
extension so that the file will be saved with the right file type.
This property will be `null` for folders.
example: https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg
format: url
nullable: true
type: string
x-box-premium-feature: true
effective_access:
description: |-
The effective access level for the shared link. This can be a more
restrictive access level than the value in the `access` field when the
enterprise settings restrict the allowed access levels.
enum:
- open
- company
- collaborators
example: company
nullable: false
type: string
effective_permission:
description: |-
The effective permissions for this shared link.
These result in the more restrictive combination of
the share link permissions and the item permissions set
by the administrator, the owner, and any ancestor item
such as a folder.
enum:
- can_edit
- can_download
- can_preview
- no_access
example: can_download
nullable: false
type: string
is_password_enabled:
description: Defines if the shared link requires a password to access the item.
example: true
nullable: false
type: boolean
permissions:
description: |-
Defines if this link allows a user to preview, edit, and download an item.
These permissions refer to the shared link only and
do not supersede permissions applied to the item itself.
properties:
can_download:
description: |-
Defines if the shared link allows for the item to be downloaded. For
shared links on folders, this also applies to any items in the folder.
This value can be set to `true` when the effective access level is
set to `open` or `company`, not `collaborators`.
example: true
nullable: false
type: boolean
can_edit:
description: |-
Defines if the shared link allows for the item to be edited.
This value can only be `true` if `can_download` is also `true` and if
the item has a type of `file`.
example: false
nullable: false
type: boolean
can_preview:
description: |-
Defines if the shared link allows for the item to be previewed.
This value is always `true`. For shared links on folders this also
applies to any items in the folder.
example: true
nullable: false
type: boolean
required:
- can_download
- can_preview
- can_edit
type: object
preview_count:
description: The number of times this item has been previewed.
example: 3
nullable: false
type: integer
unshared_at:
description: |-
The date and time when this link will be unshared. This field can only be
set by users with paid accounts.
example: 2018-04-13T13:53:23-07:00
format: date-time
nullable: true
type: string
url:
description: |-
The URL that can be used to access the item on Box.
This URL will display the item in Box's preview UI where the file
can be downloaded if allowed.
This URL will continue to work even when a custom `vanity_url`
has been set for this shared link.
example: https://www.box.com/s/vspke7y05sb214wjokpk
format: url
nullable: false
type: string
vanity_name:
description: The custom name of a shared link, as used in the `vanity_url` field.
example: my_url
nullable: true
type: string
vanity_url:
description: |-
The "Custom URL" that can also be used to preview the item on Box. Custom
URLs can only be created or modified in the Box Web application.
example: https://acme.app.box.com/v/my_url/
format: url
nullable: true
type: string
required:
- url
- accessed
- effective_access
- effective_permission
- is_password_enabled
- download_count
- preview_count
title: Shared link
type: object
- description: |-
The shared link for this folder. This will be
`null` if no shared link has been created for this
folder.
nullable: true
size:
description: |-
The folder size in bytes.
Be careful parsing this integer as its
value can get very large.
example: 629644
format: int64
nullable: false
type: integer
trashed_at:
description: The time at which this folder was put in the trash.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
description: |-
A standard representation of a folder, as returned from any
folder API endpoints by default
required:
- size
- path_collection
- created_by
- modified_by
- owned_by
- item_status
- item_collection
title: Folder
type: object
x-box-resource-id: folder
x-box-variant: standard
Folder--Base:
description: |-
The bare basic representation of a folder, the minimal
amount of fields returned when using the `fields` query
parameter.
properties:
etag:
description: |-
The HTTP `etag` of this folder. This can be used within some API
endpoints in the `If-Match` and `If-None-Match` headers to only
perform changes on the folder if (no) changes have happened.
example: "1"
nullable: true
type: string
id:
description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting a folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folders/123`
the `folder_id` is `123`.
example: "12345"
nullable: false
type: string
type:
description: "`folder`"
enum:
- folder
example: folder
nullable: false
type: string
required:
- id
- type
title: Folder (Base)
type: object
x-box-resource-id: folder--base
x-box-sanitized: true
x-box-tag: folders
x-box-variant: base
x-box-variants:
- base
- mini
- standard
- full
Folder--Full:
allOf:
- $ref: "#/components/schemas/Folder"
- properties:
allowed_invitee_roles:
description: |-
A list of the types of roles that user can be invited at
when sharing this folder.
example:
- editor
items:
enum:
- editor
- viewer
- previewer
- uploader
- previewer uploader
- viewer uploader
- co-owner
type: string
nullable: false
type: array
allowed_shared_link_access_levels:
description: |-
A list of access levels that are available
for this folder.
For some folders, like the root folder, this will always
be an empty list as sharing is not allowed at that level.
example:
- open
items:
enum:
- open
- company
- collaborators
type: string
nullable: false
type: array
can_non_owners_invite:
allOf:
- description: |-
Specifies if users who are not the owner
of the folder can invite new collaborators to the folder.
example: true
type: boolean
- nullable: false
can_non_owners_view_collaborators:
description: |-
Specifies if collaborators who are not owners
of this folder are restricted from viewing other
collaborations on this folder.
It also restricts non-owners from inviting new
collaborators.
example: true
type: boolean
classification:
allOf:
- description: The classification applied to an item
properties:
color:
description: |-
The color that is used to display the
classification label in a user-interface. Colors are defined by the admin
or co-admin who created the classification in the Box web app.
example: "#FF0000"
type: string
definition:
description: An explanation of the meaning of this classification.
example: Content that should not be shared outside the company.
type: string
name:
description: The name of the classification
example: Top Secret
type: string
type: object
- description: Details about the classification applied to this folder.
- nullable: true
has_collaborations:
description: Specifies if this folder has any other collaborators.
example: true
nullable: false
type: boolean
is_accessible_via_shared_link:
description: |-
Specifies if the folder can be accessed
with the direct shared link or a shared link
to a parent folder.
enum:
- true
- false
example: true
type: boolean
is_collaboration_restricted_to_enterprise:
allOf:
- description: |-
Specifies if new invites to this folder are restricted to users
within the enterprise. This does not affect existing
collaborations.
example: true
type: boolean
- nullable: false
is_externally_owned:
description: |-
Specifies if this folder is owned by a user outside of the
authenticated enterprise.
example: true
nullable: false
type: boolean
metadata:
allOf:
- additionalProperties:
additionalProperties:
$ref: "#/components/schemas/Metadata"
description: |-
A list of metadata instances, nested within key-value pairs of their `scope`
and `templateKey`.
example:
marketingCollateral:
$canEdit: true
$id: 01234500-12f1-1234-aa12-b1d234cb567e
$parent: folder_59449484661
$scope: enterprise_27335
$template: marketingCollateral
$type: properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0
$typeVersion: 2
$version: 1
type: object
description: |-
A list of metadata instances, nested within key-value pairs of their `scope`
and `templateKey`.
To access the metadata for a file or folder, first use the
metadata endpoints to determine the metadata templates available to your
enterprise.
Then use the `GET /files/:id` or `GET /folder/:id`
endpoint with the `fields` query parameter to get
the metadata by ID.
To request a metadata instance for a particular `scope` and `templateKey`
use the following format for the `fields` parameter:
`metadata..`
For example, `?fields=metadata.enterprise_27335.marketingCollateral`.
example:
enterprise_27335:
marketingCollateral:
$canEdit: true
$id: 01234500-12f1-1234-aa12-b1d234cb567e
$parent: folder_59449484661
$scope: enterprise_27335
$template: marketingCollateral
$type: properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0
$typeVersion: 2
$version: 1
title: Item metadata instances
type: object
- description: |-
An object containing the metadata instances that have been
attached to this folder.
Each metadata instance is uniquely identified by its `scope` and
`templateKey`. There can only be one instance of any metadata
template attached to each folder. Each metadata instance is nested
within an object with the `templateKey` as the key, which again
itself is nested in an object with the `scope` as the key.
permissions:
allOf:
- allOf:
- description: The permissions that the authenticated user has for an item.
properties:
can_delete:
description: Specifies if the current user can delete this item.
example: true
nullable: false
type: boolean
can_download:
description: Specifies if the current user can download this item.
example: true
nullable: false
type: boolean
can_invite_collaborator:
description: |-
Specifies if the current user can invite new
users to collaborate on this item, and if the user can
update the role of a user already collaborated on this
item.
example: true
nullable: false
type: boolean
can_rename:
description: Specifies if the user can rename this item.
example: true
nullable: false
type: boolean
can_set_share_access:
description: |-
Specifies if the user can change the access level of an
existing shared link on this item.
example: true
nullable: false
type: boolean
can_share:
description: Specifies if the user can create a shared link for this item.
example: true
nullable: false
type: boolean
required:
- can_delete
- can_download
- can_invite_collaborator
- can_rename
- can_set_share_access
- can_share
type: object
- properties:
can_upload:
description: Specifies if the user can upload into this folder.
example: true
nullable: false
type: boolean
description: The permissions that the authenticated user has for a folder.
required:
- can_upload
type: object
- description: |-
Describes the permissions that the current user has
for this folder
- nullable: false
sync_state:
allOf:
- description: |-
Specifies whether a folder should be synced to a
user's device or not. This is used by Box Sync
(discontinued) and is not used by Box Drive.
enum:
- synced
- not_synced
- partially_synced
example: synced
nullable: false
type: string
tags:
allOf:
- description: |-
The tags for this item. These tags are shown in
the Box web app and mobile apps next to an item.
To add or remove a tag, retrieve the item's current tags,
modify them, and then update this field.
There is a limit of 100 tags per item, and 10,000
unique tags per enterprise.
example:
- approved
items:
type: string
maxItems: 100
minItems: 1
type: array
- nullable: false
watermark_info:
allOf:
- description: Details about the watermark applied to this item
properties:
is_watermarked:
description: Specifies if this item has a watermark applied.
example: true
nullable: false
type: boolean
type: object
- description: Details about the watermark applied to this folder
- nullable: false
description: |-
A full representation of a folder, as can be returned from any
folder API endpoints by default
title: Folder (Full)
type: object
x-box-resource-id: folder--full
x-box-variant: full
Folder--Mini:
allOf:
- $ref: "#/components/schemas/Folder--Base"
- properties:
name:
description: The name of the folder.
example: Contracts
nullable: false
type: string
sequence_id:
allOf:
- description: |-
A numeric identifier that represents the most recent user event
that has been applied to this item.
This can be used in combination with the `GET /events`-endpoint
to filter out user events that would have occurred before this
identifier was read.
An example would be where a Box Drive-like application
would fetch an item via the API, and then listen to incoming
user events for changes to the item. The application would
ignore any user events where the `sequence_id` in the event
is smaller than or equal to the `sequence_id` in the originally
fetched resource.
example: "3"
nullable: false
type: string
- nullable: false
description: |-
A mini representation of a file version, used when
nested under another resource.
title: Folder (Mini)
type: object
x-box-resource-id: folder--mini
x-box-variant: mini
FolderLock:
description: |-
Folder locks define access restrictions placed by folder owners
to prevent specific folders from being moved or deleted.
properties:
created_at:
description: When the folder lock object was created.
example: 2020-09-14T23:12:53Z
format: date-time
type: string
created_by:
allOf:
- $ref: "#/components/schemas/User--Base"
- description: The user or group that created the lock.
folder:
allOf:
- $ref: "#/components/schemas/Folder--Mini"
- description: The folder that the lock applies to.
id:
description: The unique identifier for this folder lock.
example: "12345678"
type: string
lock_type:
description: The lock type, always `freeze`.
example: freeze
type: string
locked_operations:
description: |
The operations that have been locked. Currently the `move`
and `delete` operations cannot be locked separately, and both need to be
set to `true`.
properties:
delete:
description: Whether deleting the folder is restricted.
example: true
nullable: false
type: boolean
move:
description: Whether moving the folder is restricted.
example: true
nullable: false
type: boolean
required:
- move
- delete
type: object
type:
description: The object type, always `folder_lock`.
example: folder_lock
type: string
title: Folder Lock
type: object
x-box-resource-id: folder_lock
x-box-tag: folder_locks
FolderLocks:
allOf:
- description: |-
The part of an API response that describes marker
based pagination
properties:
limit:
description: |-
The limit that was used for these entries. This will be the same as the
`limit` query parameter unless that value exceeded the maximum value
allowed. The maximum value varies by API.
example: 1000
format: int64
type: integer
next_marker:
description: The marker for the start of the next page of results.
example: 3000
format: int64
type: integer
prev_marker:
description: The marker for the start of the previous page of results.
example: 1000
format: int64
type: integer
type: object
- properties:
entries:
items:
$ref: "#/components/schemas/FolderLock"
type: array
description: A list of folder locks
title: Folder Locks
type: object
x-box-resource-id: folder_locks
x-box-tag: folder_locks
Group:
allOf:
- $ref: "#/components/schemas/Group--Mini"
- properties:
created_at:
description: When the group object was created
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
modified_at:
description: When the group object was last modified
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
description: |-
A standard representation of a group, as returned from any
group API endpoints by default
title: Group
type: object
x-box-resource-id: group
x-box-variant: standard
Group--Base:
description: A base representation of a group.
properties:
id:
description: The unique identifier for this object
example: "11446498"
type: string
type:
description: "`group`"
enum:
- group
example: group
type: string
title: Group (Base)
type: object
x-box-resource-id: group--base
x-box-sanitized: true
x-box-tag: groups
x-box-variant: base
x-box-variants:
- base
- mini
- standard
- full
Group--Full:
allOf:
- $ref: "#/components/schemas/Group"
- properties:
description:
description: Human readable description of the group.
example: Support Group - as imported from Active Directory
maxLength: 255
type: string
external_sync_identifier:
description: |-
An arbitrary identifier that can be used by
external group sync tools to link this Box Group to
an external group. Example values of this field
could be an Active Directory Object ID or a Google
Group ID. We recommend you use of this field in
order to avoid issues when group names are updated in
either Box or external systems.
example: AD:123456
type: string
invitability_level:
description: |-
Specifies who can invite the group to collaborate
on items.
When set to `admins_only` the enterprise admin, co-admins,
and the group's admin can invite the group.
When set to `admins_and_members` all the admins listed
above and group members can invite the group.
When set to `all_managed_users` all managed users in the
enterprise can invite the group.
enum:
- admins_only
- admins_and_members
- all_managed_users
example: admins_only
type: string
member_viewability_level:
description: |-
Specifies who can view the members of the group
(Get Memberships for Group).
* `admins_only` - the enterprise admin, co-admins, group's
group admin
* `admins_and_members` - all admins and group members
* `all_managed_users` - all managed users in the
enterprise
enum:
- admins_only
- admins_and_members
- all_managed_users
example: admins_only
type: string
permissions:
allOf:
- description: The permissions that the authenticated user has for a group.
properties:
can_invite_as_collaborator:
description: Specifies if the user can invite the group to collaborate on any items.
example: true
type: boolean
type: object
- description: |-
Describes the permissions that the current user has
for this group.
provenance:
description: |-
Keeps track of which external source this group is
coming from (e.g. "Active Directory", "Google Groups",
"Facebook Groups"). Setting this will
also prevent Box users from editing the group name
and its members directly via the Box web application.
This is desirable for one-way syncing of groups.
example: Active Directory
maxLength: 255
type: string
description: |-
Groups contain a set of users, and can be used in place of
users in some operations, such as collaborations.
title: Group (Full)
type: object
x-box-resource-id: group--full
x-box-variant: full
Group--Mini:
allOf:
- $ref: "#/components/schemas/Group--Base"
- properties:
group_type:
description: The type of the group.
enum:
- managed_group
- all_users_group
example: managed_group
type: string
name:
description: The name of the group
example: Support
type: string
description: |-
Mini representation of a group, including id and name of
group.
title: Group (Mini)
type: object
x-box-resource-id: group--mini
x-box-variant: mini
GroupMembership:
description: |-
Membership is used to signify that a user is part of a
group.
properties:
created_at:
description: The time this membership was created.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
group:
allOf:
- $ref: "#/components/schemas/Group--Mini"
- description: The group that the membership applies to
id:
description: The unique identifier for this group membership
example: "11446498"
type: string
modified_at:
description: The time this membership was last modified.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
role:
description: The role of the user in the group.
enum:
- member
- admin
example: member
type: string
type:
description: "`group_membership`"
enum:
- group_membership
example: group_membership
type: string
user:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user that the membership applies to
title: Group membership
type: object
x-box-resource-id: group_membership
x-box-tag: memberships
GroupMemberships:
allOf:
- description: The part of an API response that describes pagination
properties:
limit:
description: |-
The limit that was used for these entries. This will be the same as the
`limit` query parameter unless that value exceeded the maximum value
allowed. The maximum value varies by API.
example: 1000
format: int64
type: integer
offset:
description: |-
The 0-based offset of the first entry in this set. This will be the same
as the `offset` query parameter.
This field is only returned for calls that use offset-based pagination.
For marker-based paginated APIs, this field will be omitted.
example: 2000
format: int64
type: integer
order:
description: |-
The order by which items are returned.
This field is only returned for calls that use offset-based pagination.
For marker-based paginated APIs, this field will be omitted.
items:
description: The order in which a pagination is ordered
properties:
by:
description: The field to order by
example: type
type: string
direction:
description: The direction to order by, either ascending or descending
enum:
- ASC
- DESC
example: ASC
type: string
type: object
type: array
total_count:
description: |-
One greater than the offset of the last entry in the entire collection.
The total number of entries in the collection may be less than
`total_count`.
This field is only returned for calls that use offset-based pagination.
For marker-based paginated APIs, this field will be omitted.
example: 5000
format: int64
type: integer
type: object
- properties:
entries:
items:
$ref: "#/components/schemas/GroupMembership"
type: array
description: A list of group memberships.
title: Group memberships
type: object
x-box-resource-id: group_memberships
x-box-tag: memberships
Groups:
allOf:
- description: The part of an API response that describes pagination
properties:
limit:
description: |-
The limit that was used for these entries. This will be the same as the
`limit` query parameter unless that value exceeded the maximum value
allowed. The maximum value varies by API.
example: 1000
format: int64
type: integer
offset:
description: |-
The 0-based offset of the first entry in this set. This will be the same
as the `offset` query parameter.
This field is only returned for calls that use offset-based pagination.
For marker-based paginated APIs, this field will be omitted.
example: 2000
format: int64
type: integer
order:
description: |-
The order by which items are returned.
This field is only returned for calls that use offset-based pagination.
For marker-based paginated APIs, this field will be omitted.
items:
description: The order in which a pagination is ordered
properties:
by:
description: The field to order by
example: type
type: string
direction:
description: The direction to order by, either ascending or descending
enum:
- ASC
- DESC
example: ASC
type: string
type: object
type: array
total_count:
description: |-
One greater than the offset of the last entry in the entire collection.
The total number of entries in the collection may be less than
`total_count`.
This field is only returned for calls that use offset-based pagination.
For marker-based paginated APIs, this field will be omitted.
example: 5000
format: int64
type: integer
type: object
- properties:
entries:
items:
$ref: "#/components/schemas/Group--Mini"
type: array
description: A list of groups.
title: Groups
type: object
x-box-resource-id: groups
x-box-tag: groups
Invite:
description: An invite for a user to an enterprise.
properties:
actionable_by:
$ref: "#/components/schemas/User--Mini"
created_at:
description: When the invite was created
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
id:
description: The unique identifier for this invite
example: "11446498"
type: string
invited_by:
$ref: "#/components/schemas/User--Mini"
invited_to:
description: A representation of a Box enterprise
properties:
id:
description: The unique identifier for this enterprise.
example: "11446498"
type: string
name:
description: The name of the enterprise
example: Acme Inc.
type: string
type:
description: "`enterprise`"
enum:
- enterprise
example: enterprise
type: string
title: Enterprise
type: object
modified_at:
description: When the invite was modified.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
status:
description: The status of the invite
example: pending
type: string
type:
description: "`invite`"
enum:
- invite
example: invite
type: string
title: Invite
type: object
x-box-resource-id: invite
x-box-tag: invites
Items:
allOf:
- description: The part of an API response that describes pagination
properties:
limit:
description: |-
The limit that was used for these entries. This will be the same as the
`limit` query parameter unless that value exceeded the maximum value
allowed. The maximum value varies by API.
example: 1000
format: int64
type: integer
offset:
description: |-
The 0-based offset of the first entry in this set. This will be the same
as the `offset` query parameter.
This field is only returned for calls that use offset-based pagination.
For marker-based paginated APIs, this field will be omitted.
example: 2000
format: int64
type: integer
order:
description: |-
The order by which items are returned.
This field is only returned for calls that use offset-based pagination.
For marker-based paginated APIs, this field will be omitted.
items:
description: The order in which a pagination is ordered
properties:
by:
description: The field to order by
example: type
type: string
direction:
description: The direction to order by, either ascending or descending
enum:
- ASC
- DESC
example: ASC
type: string
type: object
type: array
total_count:
description: |-
One greater than the offset of the last entry in the entire collection.
The total number of entries in the collection may be less than
`total_count`.
This field is only returned for calls that use offset-based pagination.
For marker-based paginated APIs, this field will be omitted.
example: 5000
format: int64
type: integer
type: object
- properties:
entries:
description: The items in this collection.
items:
oneOf:
- $ref: "#/components/schemas/File--Mini"
- $ref: "#/components/schemas/Folder--Mini"
- $ref: "#/components/schemas/WebLink--Mini"
type: array
description: |-
A list of files, folders, and web links in
their mini representation.
title: Items
type: object
x-box-resource-id: items
x-box-tag: folders
KeywordSkillCard:
description: A skill card that contains a set of keywords
properties:
created_at:
description: The optional date and time this card was created at.
example: 2018-04-13T13:53:23-07:00
format: date-time
type: string
entries:
description: An list of entries in the metadata card.
items:
description: An entry in the `entries` attribute of a metadata card
properties:
text:
description: The text of the keyword.
example: keyword1
type: string
type: object
type: array
invocation:
description: |-
The invocation of this service, used to track
which instance of a service applied the metadata.
properties:
id:
description: |-
A custom identifier that represent the instance of
the service that applied this metadata. For example,
if your `image-recognition-service` runs on multiple
nodes, this field can be used to identify the ID of
the node that was used to apply the metadata.
example: image-recognition-service-123
type: string
type:
description: "`skill_invocation`"
enum:
- skill_invocation
example: skill_invocation
type: string
required:
- type
- id
type: object
skill:
description: The service that applied this metadata.
properties:
id:
description: |-
A custom identifier that represent the service that
applied this metadata.
example: image-recognition-service
type: string
type:
description: "`service`"
enum:
- service
example: service
type: string
required:
- type
- id
type: object
skill_card_title:
description: The title of the card.
properties:
code:
description: An optional identifier for the title.
example: labels
type: string
message:
description: The actual title to show in the UI.
example: Labels
type: string
required:
- message
type: object
skill_card_type:
description: "`keyword`"
enum:
- keyword
example: keyword
type: string
type:
description: "`skill_card`"
enum:
- skill_card
example: skill_card
type: string
required:
- type
- skill_card_type
- skill
- invocation
- entries
title: Keyword Skill Card
type: object
x-box-resource-id: keyword_skill_card
x-box-tag: skills
LegalHoldPolicies:
allOf:
- description: |-
The part of an API response that describes marker
based pagination
properties:
limit:
description: |-
The limit that was used for these entries. This will be the same as the
`limit` query parameter unless that value exceeded the maximum value
allowed. The maximum value varies by API.
example: 1000
format: int64
type: integer
next_marker:
description: The marker for the start of the next page of results.
example: 3000
format: int64
type: integer
prev_marker:
description: The marker for the start of the previous page of results.
example: 1000
format: int64
type: integer
type: object
- properties:
entries:
items:
$ref: "#/components/schemas/LegalHoldPolicy"
type: array
description: A list of legal hold policies.
title: Legal hold policies
type: object
x-box-resource-id: legal_hold_policies
x-box-tag: legal_hold_policies
LegalHoldPolicy:
allOf:
- $ref: "#/components/schemas/LegalHoldPolicy--Mini"
- properties:
assignment_counts:
description: Counts of assignments within this a legal hold policy by item type
properties:
file:
description: The number of files this policy is applied to
example: 3
format: int64
type: integer
file_version:
description: The number of file versions this policy is applied to
example: 4
format: int64
type: integer
folder:
description: The number of folders this policy is applied to
example: 2
format: int64
type: integer
user:
description: The number of users this policy is applied to
example: 1
format: int64
type: integer
type: object
created_at:
description: When the legal hold policy object was created
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
created_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who created the legal hold policy object
deleted_at:
description: |-
When the policy release request was sent. (Because
it can take time for a policy to fully delete, this
isn't quite the same time that the policy is fully deleted).
If `null`, the policy was not deleted.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
description:
description: |-
Description of the legal hold policy. Optional
property with a 500 character limit.
example: Postman created policy
maxLength: 500
type: string
filter_ended_at:
description: |-
User-specified, optional date filter applies to
Custodian assignments only
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
filter_started_at:
description: |-
User-specified, optional date filter applies to
Custodian assignments only
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
modified_at:
description: |-
When the legal hold policy object was modified.
Does not update when assignments are added or removed.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
policy_name:
description: Name of the legal hold policy.
example: Policy 4
maxLength: 254
type: string
release_notes:
description: Optional notes about why the policy was created.
example: Example
maxLength: 500
type: string
status:
description: |-
* 'active' - the policy is not in a transition state
* 'applying' - that the policy is in the process of
being applied
* 'releasing' - that the process is in the process
of being released
* 'released' - the policy is no longer active
enum:
- active
- applying
- releasing
- released
example: active
type: string
description: |-
Legal Hold Policy information describes the basic
characteristics of the Policy, such as name, description,
and filter dates.
title: Legal hold policy
type: object
x-box-resource-id: legal_hold_policy
x-box-variant: standard
LegalHoldPolicy--Mini:
description: A mini legal hold policy
properties:
id:
description: The unique identifier for this legal hold policy
example: "11446498"
type: string
type:
description: "`legal_hold_policy`"
enum:
- legal_hold_policy
example: legal_hold_policy
type: string
title: Legal hold policy (Mini)
type: object
x-box-resource-id: legal_hold_policy--mini
x-box-tag: legal_hold_policies
x-box-variant: mini
x-box-variants:
- mini
- standard
LegalHoldPolicyAssignment:
allOf:
- $ref: "#/components/schemas/LegalHoldPolicyAssignment--Base"
- properties:
assigned_at:
description: |-
When the legal hold policy assignment object was
created
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
assigned_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: |-
The user who created the legal hold policy
assignment
assigned_to:
allOf:
- oneOf:
- $ref: "#/components/schemas/File"
- $ref: "#/components/schemas/Folder"
- $ref: "#/components/schemas/WebLink"
- description: |-
The item that the the legal hold policy
is assigned to. Includes type and ID.
deleted_at:
description: |-
When the assignment release request was sent.
(Because it can take time for an assignment to fully
delete, this isn't quite the same time that the
assignment is fully deleted). If null, Assignment
was not deleted.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
legal_hold_policy:
allOf:
- $ref: "#/components/schemas/LegalHoldPolicy--Mini"
- description: |-
The policy that the legal hold policy assignment
is part of
description: |-
Legal Hold Assignments are used to assign Legal Hold
Policies to Users, Folders, Files, or File Versions.
Creating a Legal Hold Assignment puts a hold
on the File-Versions that belong to the Assignment's
'apply-to' entity.
title: Legal hold policy assignment
type: object
x-box-resource-id: legal_hold_policy_assignment
x-box-tag: legal_hold_policy_assignments
LegalHoldPolicyAssignment--Base:
description: |-
Legal Hold Assignments are used to assign Legal Hold
Policies to Users, Folders, Files, or File Versions.
Creating a Legal Hold Assignment puts a hold
on the File-Versions that belong to the Assignment's
'apply-to' entity.
properties:
id:
description: The unique identifier for this legal hold assignment
example: "11446498"
type: string
type:
description: "`legal_hold_policy_assignment`"
enum:
- legal_hold_policy_assignment
example: legal_hold_policy_assignment
type: string
title: Legal hold policy assignment (Base)
type: object
x-box-resource-id: legal_hold_policy_assignment--base
x-box-sanitized: true
x-box-tag: legal_hold_policy_assignments
x-box-variant: base
x-box-variants:
- base
- standard
LegalHoldPolicyAssignments:
allOf:
- description: |-
The part of an API response that describes marker
based pagination
properties:
limit:
description: |-
The limit that was used for these entries. This will be the same as the
`limit` query parameter unless that value exceeded the maximum value
allowed. The maximum value varies by API.
example: 1000
format: int64
type: integer
next_marker:
description: The marker for the start of the next page of results.
example: 3000
format: int64
type: integer
prev_marker:
description: The marker for the start of the previous page of results.
example: 1000
format: int64
type: integer
type: object
- properties:
entries:
items:
$ref: "#/components/schemas/LegalHoldPolicyAssignment--Base"
type: array
description: A list of legal hold policies assignments.
title: Legal hold policy assignments
type: object
x-box-resource-id: legal_hold_policy_assignments
x-box-tag: legal_hold_policy_assignments
Metadata:
allOf:
- $ref: "#/components/schemas/Metadata--Base"
description: |-
An instance of a metadata template, which has been applied to a file or
folder.
title: Metadata instance
type: object
x-box-resource-id: metadata
x-box-tag: file_metadata
x-box-variant: standard
Metadata--Base:
description: The base representation of a metadata instance.
properties:
$parent:
description: |-
The identifier of the item that this metadata instance
has been attached to. This combines the `type` and the `id`
of the parent in the form `{type}_{id}`.
example: folder_59449484661,
type: string
$scope:
description: |-
An ID for the scope in which this template
has been applied. This will be `enterprise_{enterprise_id}` for templates
defined for use in this enterprise, and `global` for general templates
that are available to all enterprises using Box.
example: enterprise_27335
type: string
$template:
description: The name of the template
example: marketingCollateral
type: string
$version:
description: |-
The version of the metadata instance. This version starts at 0 and
increases every time a user-defined property is modified.
example: 1
type: integer
title: Metadata instance (Base)
type: object
x-box-resource-id: metadata--base
x-box-sanitized: true
x-box-tag: file_metadata
x-box-variant: base
x-box-variants:
- base
- standard
- full
Metadata--Full:
allOf:
- $ref: "#/components/schemas/Metadata"
- properties:
$canEdit:
description: Whether the user can edit this metadata instance.
example: true
type: boolean
$id:
description: A UUID to identify the metadata instance.
example: 01234500-12f1-1234-aa12-b1d234cb567e
format: uuid
maxLength: 36
type: string
$type:
description: |-
A unique identifier for the "type" of this instance. This is an
internal system property and should not be used by a client
application.
example: properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0
type: string
$typeVersion:
description: |-
The last-known version of the template of the object. This is an
internal system property and should not be used by a client
application.
example: 2
type: integer
- additionalProperties:
example: Aaron Levie
x-box-example-key: name
description: |-
An instance of a metadata template, which has been applied to a file or
folder.
title: Metadata instance (Full)
type: object
x-box-resource-id: metadata--full
x-box-variant: full
MetadataCascadePolicies:
allOf:
- description: |-
The part of an API response that describes marker
based pagination
properties:
limit:
description: |-
The limit that was used for these entries. This will be the same as the
`limit` query parameter unless that value exceeded the maximum value
allowed. The maximum value varies by API.
example: 1000
format: int64
type: integer
next_marker:
description: The marker for the start of the next page of results.
example: 3000
format: int64
type: integer
prev_marker:
description: The marker for the start of the previous page of results.
example: 1000
format: int64
type: integer
type: object
- properties:
entries:
items:
$ref: "#/components/schemas/MetadataCascadePolicy"
type: array
description: A list of metadata cascade policies.
title: Metadata cascade policies
type: object
x-box-resource-id: metadata_cascade_policies
x-box-tag: metadata_cascade_policies
MetadataCascadePolicy:
description: |-
A metadata cascade policy automatically applies a metadata template instance
to all the files and folders within the targeted folder.
properties:
id:
description: The ID of the metadata cascade policy object
example: 6fd4ff89-8fc1-42cf-8b29-1890dedd26d7
type: string
owner_enterprise:
description: The enterprise that owns this policy.
properties:
id:
description: The ID of the enterprise that owns the policy.
example: "690678"
type: string
type:
description: "`enterprise`"
enum:
- enterprise
example: enterprise
type: string
type: object
parent:
description: Represent the folder the policy is applied to.
properties:
id:
description: The ID of the folder the policy is applied to.
example: "1234567"
type: string
type:
description: "`folder`"
enum:
- folder
example: folder
type: string
type: object
scope:
description: |-
The scope of the of the template that is cascaded down to the folder's
children.
enum:
- global
- enterprise_*
example: global
type: string
templateKey:
description: |-
The key of the template that is cascaded down to the folder's
children.
In many cases the template key is automatically derived
of its display name, for example `Contract Template` would
become `contractTemplate`. In some cases the creator of the
template will have provided its own template key.
Please [list the templates for an enterprise][list], or
get all instances on a [file][file] or [folder][folder]
to inspect a template's key.
[list]: e://get-metadata-templates-enterprise
[file]: e://get-files-id-metadata
[folder]: e://get-folders-id-metadata
example: productInfo
type: string
type:
description: "`metadata_cascade_policy`"
enum:
- metadata_cascade_policy
example: metadata_cascade_policy
type: string
title: Metadata cascade policy
type: object
x-box-resource-id: metadata_cascade_policy
x-box-tag: metadata_cascade_policies
MetadataFieldFilterDateRange:
additionalProperties:
description: Match a `date` metadata field to a range of values.
example:
gt: 2016-08-01T00:00:00Z
lt: 2017-08-01T00:00:00Z
properties:
gt:
description: |-
Specifies the (inclusive) lower bound for the metadata field
value. The value of a field must be greater than (`gt`) or
equal to this value for the search query to match this
template.
example: 2016-08-01T00:00:00Z
format: date-time
type: string
lt:
description: |-
Specifies the (inclusive) upper bound for the metadata field
value. The value of a field must be lower than (`lt`) or
equal to this value for the search query to match this
template.
example: 2017-08-01T00:00:00Z
format: date-time
type: string
type: object
x-box-example-key: expirationDate
description: |-
Specifies which `date` field on the template to filter the search
results by, specifying a range of dates that can match.
example:
expirationDate:
gt: 2016-08-01T00:00:00Z
lt: 2017-08-01T00:00:00Z
title: Metadata field filter (date range)
type: object
x-box-resource-id: metadata_field_filter_date_range
MetadataFieldFilterFloat:
additionalProperties:
description: |-
A mapping between a metadata `float` field key and
the value to match search results on.
example: 10000
type: number
x-box-example-key: contractValue
description: |-
Specifies which `float` field on the template to filter the search
results by.
example:
contractValue: 10000
title: Metadata field filter (float)
type: object
x-box-resource-id: metadata_field_filter_float
MetadataFieldFilterFloatRange:
additionalProperties:
description: |-
Specifies which `float` field on the template to filter the search
results by, specifying a range of values that can match.
example:
gt: 100000
lt: 200000
properties:
gt:
description: |-
Specifies the (inclusive) lower bound for the metadata field
value. The value of a field must be greater than (`gt`) or
equal to this value for the search query to match this
template.
example: 100000
type: number
lt:
description: |-
Specifies the (inclusive) upper bound for the metadata field
value. The value of a field must be lower than (`lt`) or
equal to this value for the search query to match this
template.
example: 200000
type: number
type: object
x-box-example-key: value
description: |-
Specifies which `float` field on the template to filter the search
results by, specifying a range of values that can match.
example:
contractValue:
gt: 100000
lt: 200000
title: Metadata field filter (float range)
type: object
x-box-resource-id: metadata_field_filter_float_range
MetadataFieldFilterMultiSelect:
additionalProperties:
description: |-
A mapping between a metadata `multiSelect` field key and
the one or more values to match search results on.
When performing a search, the query will essentially
perform an `OR` operation to match any template where any of
the provided values match this field.
example:
- online
- enterprise
items:
type: string
type: array
x-box-example-key: category
description: |-
Specifies the values to match for a `multiSelect` metadata
field. When performing a search, the query will essentially
perform an `OR` operation to match any template where any of
the provided values match this field.
example:
category:
- online
- enterprise
title: Metadata field filter (multi-select)
type: object
x-box-resource-id: metadata_field_filter_multi_select
MetadataFieldFilterString:
additionalProperties:
description: |-
A mapping between a metadata `string` field key and
the value to match search results on.
example: online
type: string
x-box-example-key: category
description: |-
Specifies which text field on the template to filter the search
results by.
example:
category: online
title: Metadata field filter (string)
type: object
x-box-resource-id: metadata_field_filter_string
MetadataFilter:
description: A metadata template to filter the search results by.
properties:
filters:
allOf:
- anyOf:
- $ref: "#/components/schemas/MetadataFieldFilterString"
- $ref: "#/components/schemas/MetadataFieldFilterFloat"
- $ref: "#/components/schemas/MetadataFieldFilterMultiSelect"
- $ref: "#/components/schemas/MetadataFieldFilterFloatRange"
- $ref: "#/components/schemas/MetadataFieldFilterDateRange"
- description: |-
Specifies which fields on the template to filter the search
results by. When more than one field is specified, the query
performs a logical `AND` to ensure that the instance of the
template matches each of the fields specified.
- example:
category: online
contractValue: 1000000
scope:
description: |-
Specifies the scope of the template to filter search results by.
This will be `enterprise_{enterprise_id}` for templates defined
for use in this enterprise, and `global` for general templates
that are available to all enterprises using Box.
enum:
- global
- enterprise
- enterprise_{enterprise_id}
example: enterprise
type: string
templateKey:
description: |-
The key of the template to filter search results by.
In many cases the template key is automatically derived
of its display name, for example `Contract Template` would
become `contractTemplate`. In some cases the creator of the
template will have provided its own template key.
Please [list the templates for an enterprise][list], or
get all instances on a [file][file] or [folder][folder]
to inspect a template's key.
[list]: e://get-metadata-templates-enterprise
[file]: e://get-files-id-metadata
[folder]: e://get-folders-id-metadata
example: contract
type: string
title: Metadata filter
type: object
x-box-resource-id: metadata_filter
x-box-tag: search
MetadataQuery:
description: |-
Create a search using SQL-like syntax to return items that match specific
metadata.
properties:
ancestor_folder_id:
description: |-
The ID of the folder that you are restricting the query to. A
value of zero will return results from all folders you have access
to. A non-zero value will only return results found in the folder
corresponding to the ID or in any of its subfolders.
example: "0"
type: string
fields:
description: |-
By default, this endpoint returns only the most basic info about the items for
which the query matches. This attribute can be used to specify a list of
additional attributes to return for any item, including its metadata.
This attribute takes a list of item fields, metadata template identifiers,
or metadata template field identifiers.
For example:
* `created_by` will add the details of the user who created the item to
the response.
* `metadata..` will return the mini-representation
of the metadata instance identified by the `scope` and `templateKey`.
* `metadata...` will return all the mini-representation
of the metadata instance identified by the `scope` and `templateKey` plus
the field specified by the `field` name. Multiple fields for the same
`scope` and `templateKey` can be defined.
example:
- extension
- created_at
- item_status
- metadata.enterprise_1234.contracts
- metadata.enterprise_1234.regions.location
items:
type: string
type: array
from:
description: |-
Specifies the template used in the query. Must be in the form
`scope.templateKey`. Not all templates can be used in this field,
most notably the built-in, Box-provided classification templates
can not be used in a query.
example: enterprise_123456.someTemplate
type: string
limit:
default: 100
description: |-
A value between 0 and 100 that indicates the maximum number of results
to return for a single request. This only specifies a maximum
boundary and will not guarantee the minimum number of results
returned.
example: 50
maximum: 100
minimum: 0
type: integer
marker:
description: Marker to use for requesting the next page.
example: AAAAAmVYB1FWec8GH6yWu2nwmanfMh07IyYInaa7DZDYjgO1H4KoLW29vPlLY173OKsci6h6xGh61gG73gnaxoS+o0BbI1/h6le6cikjlupVhASwJ2Cj0tOD9wlnrUMHHw3/ISf+uuACzrOMhN6d5fYrbidPzS6MdhJOejuYlvsg4tcBYzjauP3+VU51p77HFAIuObnJT0ff
type: string
order_by:
description: |-
A list of template fields and directions to sort the metadata query
results by.
The ordering `direction` must be the same for each item in the array.
items:
description: |-
An object representing one of the metadata template fields to sort the
metadata query results by.
properties:
direction:
description: |-
The direction to order by, either ascending or descending.
The `ordering` direction must be the same for each item in the
array.
enum:
- ASC
- DESC
- asc
- desc
example: asc
type: string
field_key:
description: |-
The metadata template field to order by.
The `field_key` represents the `key` value of a field from the
metadata template being searched for.
example: amount
type: string
type: object
type: array
query:
description: |-
The query to perform. A query is a logical expression that is very similar
to a SQL `SELECT` statement. Values in the search query can be turned into
parameters specified in the `query_param` arguments list to prevent having
to manually insert search values into the query string.
For example, a value of `:amount` would represent the `amount` value in
`query_params` object.
example: value >= :amount
type: string
query_params:
additionalProperties:
description: |-
The value for the argument being used in the metadata search.
The type of this parameter must match the type of the corresponding
metadata template field.
example: "100"
type: string
x-box-example-key: amount
description: |-
Set of arguments corresponding to the parameters specified in the
`query`. The type of each parameter used in the `query_params` must match
the type of the corresponding metadata template field.
example:
amount: "100"
type: object
required:
- from
- ancestor_folder_id
title: Metadata query search request
type: object
MetadataQueryIndex:
description: A metadata query index
properties:
fields:
description: A list of template fields which make up the index.
items:
allOf:
- properties:
key:
description: The metadata template field key.
example: vendor name
type: string
sort_direction:
description: The sort direction of the field.
enum:
- asc
- desc
example: asc
type: string
description: The field which makes up the index.
type: object
type: array
id:
description: The ID of the metadata query index.
example: "-9876"
type: string
status:
description: The status of the metadata query index
enum:
- building
- active
- disabled
example: active
nullable: false
type: string
type:
description: Value is always `metadata_query_index`
example: metadata_query_index
nullable: false
type: string
required:
- type
- status
title: Metadata query index
type: object
x-box-resource-id: metadata_query_index
x-box-tag: search
MetadataQueryIndices:
description: A collection of metadata query indices.
properties:
entries:
description: A collection of metadata query indices.
items:
$ref: "#/components/schemas/MetadataQueryIndex"
type: array
limit:
default: 100
description: The limit that was used for this request.
example: 100
format: int64
type: integer
next_marker:
description: The marker for the start of the next page of results.
example: 0!-M7487OpVfBTNBV-XsQjU50gQFlbFFu5nArMWD7Ck61GH_Qo40M1S2xN5zWZPBzEjaQS1SOjJiQoo5BsXEl1bCVLRZ2pTqo4SKp9tyqzWQK2L51KR_nC1EgF5I_TJSFw7uO2Bx4HweGETOjh5_2oPSWw5iMkM-OvGApeR0lGFO48FDKoyzJyLgz5aogxoKd8VE09CesOOnTnmZvrW0puylDc-hFjY5YLmWFBKox3SOWiSDwKFkmZGNHyjEzza1nSwbZg6CYsAdGsDwGJhuCeTNsFzP5Mo5qx9wMloS0lSPuf2CcBInbIJzl2CKlXF3FvqhANttpm2nzdBTQRSoJyJnjVBpf4Q_HjV2eb4KIZBBlLy067UCVdv2AAWQFd5E2i6s1YiGRTtgMEZntOSUYD4IYLMWWm5Ra7ke_SP32SL3GSjbBQYIyCVQ..
type: string
title: Metadata query indices
type: object
x-box-resource-id: metadata_query_indices
x-box-tag: search
MetadataQueryResults:
description: A page of files and folders that matched the metadata query.
properties:
entries:
description: |-
The mini representation of the files and folders that match the search
terms.
By default, this endpoint returns only the most basic info about the
items. To get additional fields for each item, including any of the
metadata, use the `fields` attribute in the query.
items:
oneOf:
- $ref: "#/components/schemas/File"
- $ref: "#/components/schemas/Folder"
type: array
x-box-resource-variant: 1
limit:
default: 100
description: |-
The limit that was used for this search. This will be the same as the
`limit` query parameter unless that value exceeded the maximum value
allowed.
example: 100
format: int64
type: integer
next_marker:
description: The marker for the start of the next page of results.
example: 0!-M7487OpVfBTNBV-XsQjU50gQFlbFFu5nArMWD7Ck61GH_Qo40M1S2xN5zWZPBzEjaQS1SOjJiQoo5BsXEl1bCVLRZ2pTqo4SKp9tyqzWQK2L51KR_nC1EgF5I_TJSFw7uO2Bx4HweGETOjh5_2oPSWw5iMkM-OvGApeR0lGFO48FDKoyzJyLgz5aogxoKd8VE09CesOOnTnmZvrW0puylDc-hFjY5YLmWFBKox3SOWiSDwKFkmZGNHyjEzza1nSwbZg6CYsAdGsDwGJhuCeTNsFzP5Mo5qx9wMloS0lSPuf2CcBInbIJzl2CKlXF3FvqhANttpm2nzdBTQRSoJyJnjVBpf4Q_HjV2eb4KIZBBlLy067UCVdv2AAWQFd5E2i6s1YiGRTtgMEZntOSUYD4IYLMWWm5Ra7ke_SP32SL3GSjbBQYIyCVQ..
type: string
title: Metadata query search results
type: object
x-box-resource-id: metadata_query_results
x-box-tag: search
MetadataTemplate:
description: A template for metadata that can be applied to files and folders
properties:
copyInstanceOnItemCopy:
description: Whether or not to include the metadata when a file or folder is copied.
example: true
type: boolean
displayName:
description: |-
The display name of the template. This can be seen in the Box web app
and mobile apps.
example: Product Info
maxLength: 4096
type: string
fields:
description: |-
An ordered list of template fields which are part of the template. Each
field can be a regular text field, date field, number field, as well as a
single or multi-select list.
items:
allOf:
- description: |-
A field within a metadata template. Fields can be a basic text, date, or
number field, or a list of options.
properties:
description:
description: A description of the field. This is not shown to the user.
example: The category
maxLength: 4096
type: string
displayName:
description: |-
The display name of the field as it is shown to the user in the web and
mobile apps.
example: Category
maxLength: 4096
type: string
hidden:
description: |-
Whether this field is hidden in the UI for the user and can only be set
through the API instead.
example: true
type: boolean
key:
description: |-
A unique identifier for the field. The identifier must
be unique within the template to which it belongs.
example: category
maxLength: 256
type: string
options:
description: |-
A list of options for this field. This is used in combination with the
`enum` and `multiSelect` field types.
items:
description: |-
An option for a Metadata Template Field.
Options only need to be provided for fields of type `enum` and `multiSelect`.
Options represent the value(s) a user can select for the field either through
the UI or through the API.
properties:
key:
description: |-
The text value of the option. This represents both the display name of the
option and the internal key used when updating templates.
example: Category 1
type: string
required:
- key
title: Metadata Option (Write)
type: object
type: array
type:
description: |-
The type of field. The basic fields are a `string` field for text, a
`float` field for numbers, and a `date` fields to present the user with a
date-time picker.
Additionally, metadata templates support an `enum` field for a basic list
of items, and ` multiSelect` field for a similar list of items where the
user can select more than one value.
enum:
- string
- float
- date
- enum
- multiSelect
example: string
type: string
required:
- type
- key
- displayName
title: Metadata Field (Write)
type: object
- properties:
id:
description: The unique ID of the metadata template field.
example: 822227e0-47a5-921b-88a8-494760b2e6d2
type: string
options:
description: |-
A list of options for this field. This is used in combination
with the `enum` and `multiSelect` field types.
items:
allOf:
- description: |-
An option for a Metadata Template Field.
Options only need to be provided for fields of type `enum` and `multiSelect`.
Options represent the value(s) a user can select for the field either through
the UI or through the API.
properties:
key:
description: |-
The text value of the option. This represents both the display name of the
option and the internal key used when updating templates.
example: Category 1
type: string
required:
- key
title: Metadata Option (Write)
type: object
- properties:
id:
description: The internal unique identifier of the the option.
example: 45dc2849-a4a7-40a9-a751-4a699a589190
type: string
description: |-
An option for a Metadata Template Field.
Options are only present for fields of type `enum` and
`multiSelect`. Options represent the value(s) a user can
select for the field either through the UI or through the API.
type: object
type: array
description: |-
A field within a metadata template. Fields can be a basic text, date, or
number field, or a list of options.
type: object
type: array
hidden:
description: |-
Defines if this template is visible in the Box web app UI, or if
it is purely intended for usage through the API.
example: true
type: boolean
id:
description: The ID of the metadata template.
example: 58063d82-4128-7b43-bba9-92f706befcdf
type: string
scope:
description: |-
The scope of the metadata template can either be `global` or
`enterprise_*`. The `global` scope is used for templates that are
available to any Box enterprise. The `enterprise_*` scope represents
templates that have been created within a specific enterprise, where `*`
will be the ID of that enterprise.
example: enterprise_123456
type: string
templateKey:
description: |-
A unique identifier for the template. This identifier is unique across
the `scope` of the enterprise to which the metadata template is being
applied, yet is not necessarily unique across different enterprises.
example: productInfo
maxLength: 64
pattern: ^[a-zA-Z_][-a-zA-Z0-9_]*$
type: string
type:
description: "`metadata_template`"
enum:
- metadata_template
example: metadata_template
nullable: false
type: string
required:
- type
title: Metadata template
type: object
x-box-resource-id: metadata_template
x-box-tag: metadata_templates
MetadataTemplates:
allOf:
- description: |-
The part of an API response that describes marker
based pagination
properties:
limit:
description: |-
The limit that was used for these entries. This will be the same as the
`limit` query parameter unless that value exceeded the maximum value
allowed. The maximum value varies by API.
example: 1000
format: int64
type: integer
next_marker:
description: The marker for the start of the next page of results.
example: 3000
format: int64
type: integer
prev_marker:
description: The marker for the start of the previous page of results.
example: 1000
format: int64
type: integer
type: object
- properties:
entries:
items:
$ref: "#/components/schemas/MetadataTemplate"
type: array
description: A list of metadata templates
title: Metadata templates
type: object
x-box-resource-id: metadata_templates
x-box-tag: metadata_templates
Metadatas:
description: A list of metadata instances that have been applied to a file or folder.
properties:
entries:
description: A list of metadata instances, as applied to this file or folder.
items:
$ref: "#/components/schemas/Metadata"
type: array
limit:
description: The limit that was used for this page of results.
example: 100
type: integer
title: Metadata instances
type: object
x-box-resource-id: metadatas
x-box-tag: file_metadata
OAuth2Error:
description: An OAuth 2.0 error
properties:
error:
description: The type of the error returned.
example: invalid_client
type: string
error_description:
description: The type of the error returned.
example: The client credentials are not valid
type: string
title: OAuth 2.0 error
type: object
x-box-resource-id: oauth2_error
x-box-tag: authorization
PostOAuth2Revoke:
description: A request to revoke an OAuth 2.0 token
properties:
client_id:
description: |-
The Client ID of the application requesting to revoke the
access token.
example: ly1nj6n11vionaie65emwzk575hnnmrk
type: string
client_secret:
description: |-
The client secret of the application requesting to revoke
an access token.
example: hOzsTeFlT6ko0dme22uGbQal04SBPYc1
type: string
token:
description: The access token to revoke.
example: n22JPxrh18m4Y0wIZPIqYZK7VRrsMTWW
format: token
type: string
required:
- grant_type
title: Token revocation request
type: object
PostOAuth2Token:
description: A request for a new OAuth 2.0 token
properties:
actor_token:
description: |-
The token used to create an annotator token.
This is a JWT assertion.
Used in combination with `urn:ietf:params:oauth:grant-type:token-exchange`
as the `grant_type`.
example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ
format: token
type: string
actor_token_type:
description: |-
The type of `actor_token` passed in.
Used in combination with `urn:ietf:params:oauth:grant-type:token-exchange`
as the `grant_type`.
enum:
- urn:ietf:params:oauth:token-type:id_token
example: urn:ietf:params:oauth:token-type:id_token
format: urn
type: string
assertion:
description: |-
A JWT assertion for which to request a new access token.
Used in combination with `urn:ietf:params:oauth:grant-type:jwt-bearer`
as the `grant_type`.
example: xxxxx.yyyyy.zzzzz
format: jwt
type: string
box_shared_link:
description: |-
Full URL of the shared link on the file or folder
that the token should be generated for.
example: https://cloud.box.com/s/123456
format: url
type: string
box_subject_id:
description: |-
Used in combination with `client_credentials` as the `grant_type`.
Value is determined by `box_subject_type`. If `user` use user ID and if
`enterprise` use enterprise ID.
example: "123456789"
type: string
box_subject_type:
description: Used in combination with `client_credentials` as the `grant_type`.
enum:
- enterprise
- user
example: enterprise
type: string
client_id:
description: |-
The Client ID of the application requesting an access token.
Used in combination with `authorization_code`, `client_credentials`, or
`urn:ietf:params:oauth:grant-type:jwt-bearer` as the `grant_type`.
example: ly1nj6n11vionaie65emwzk575hnnmrk
type: string
client_secret:
description: |-
The client secret of the application requesting an access token.
Used in combination with `authorization_code`, `client_credentials`, or
`urn:ietf:params:oauth:grant-type:jwt-bearer` as the `grant_type`.
example: hOzsTeFlT6ko0dme22uGbQal04SBPYc1
type: string
code:
description: |-
The client-side authorization code passed to your application by
Box in the browser redirect after the user has successfully
granted your application permission to make API calls on their
behalf.
Used in combination with `authorization_code` as the `grant_type`.
example: n22JPxrh18m4Y0wIZPIqYZK7VRrsMTWW
format: token
type: string
grant_type:
description: |-
The type of request being made, either using a client-side obtained
authorization code, a refresh token, a JWT assertion, client credentials
grant or another access token for the purpose of downscoping a token.
enum:
- authorization_code
- refresh_token
- client_credentials
- urn:ietf:params:oauth:grant-type:jwt-bearer
- urn:ietf:params:oauth:grant-type:token-exchange
example: authorization_code
format: urn
type: string
refresh_token:
description: |-
A refresh token used to get a new access token with.
Used in combination with `refresh_token` as the `grant_type`.
example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ
format: token
type: string
resource:
description: Full URL for the file that the token should be generated for.
example: https://api.box.com/2.0/files/123456
format: url
type: string
scope:
description: |-
The space-delimited list of scopes that you want apply to the
new access token.
The `subject_token` will need to have all of these scopes or
the call will error with **401 Unauthorized**.
example: item_upload item_preview base_explorer
format: space_delimited_list
type: string
subject_token:
description: |-
The token to exchange for a downscoped token. This can be a regular
access token, a JWT assertion, or an app token.
Used in combination with `urn:ietf:params:oauth:grant-type:token-exchange`
as the `grant_type`.
example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ
format: token
type: string
subject_token_type:
description: |-
The type of `subject_token` passed in.
Used in combination with `urn:ietf:params:oauth:grant-type:token-exchange`
as the `grant_type`.
enum:
- urn:ietf:params:oauth:token-type:access_token
example: urn:ietf:params:oauth:token-type:access_token
type: string
required:
- grant_type
title: Token request
type: object
PostOAuth2Token--RefreshAccessToken:
description: |-
A request to refresh an Access Token. Use this API to refresh an expired
Access Token using a valid Refresh Token.
properties:
client_id:
description: The client ID of the application requesting to refresh the token.
example: ly1nj6n11vionaie65emwzk575hnnmrk
type: string
client_secret:
description: The client secret of the application requesting to refresh the token.
example: hOzsTeFlT6ko0dme22uGbQal04SBPYc1
type: string
grant_type:
description: The type of request being made, in this case a refresh request.
enum:
- refresh_token
example: refresh_token
format: urn
type: string
refresh_token:
description: The refresh token to refresh.
example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ
format: token
type: string
required:
- grant_type
- client_id
- client_secret
- refresh_token
title: Refresh access token
type: object
RealtimeServer:
description: |-
A real-time server that can be used for
long polling user events
properties:
max_retries:
description: |-
The maximum number of retries this server will
allow before a new long poll should be started by
getting a [new list of server](#options-events).
example: 10
type: integer
retry_timeout:
description: |-
The maximum number of seconds without a response
after which you should retry the long poll connection.
This helps to overcome network issues where the long
poll looks to be working but no packages are coming
through.
example: 610
type: integer
ttl:
description: The time in minutes for which this server is available
example: 10
type: integer
type:
description: "`realtime_server`"
example: realtime_server
type: string
url:
description: The URL for the server.
example: http://2.realtime.services.box.net/subscribe?channel=cc807c9c4869ffb1c81a&stream_type=all
type: string
title: Real-time server
type: object
x-box-resource-id: realtime_server
RealtimeServers:
description: |-
A list of real-time servers that can
be used for long-polling.
properties:
chunk_size:
description: The number of items in this response.
example: 1
format: int64
type: integer
entries:
items:
$ref: "#/components/schemas/RealtimeServer"
type: array
title: Real-time servers
type: object
x-box-resource-id: realtime_servers
x-box-tag: events
RecentItem:
description: A recent item accessed by a user.
properties:
interacted_at:
description: The time of the most recent interaction.
example: 2018-04-13T13:53:23-07:00
format: date-time
type: string
interaction_shared_link:
description: |-
If the item was accessed through a shared link it will appear here,
otherwise this will be null.
example: https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg
type: string
interaction_type:
description: |-
The most recent type of access the user performed on
the item.
enum:
- item_preview
- item_upload
- item_comment
- item_open
- item_modify
example: item_preview
type: string
item:
allOf:
- oneOf:
- $ref: "#/components/schemas/File"
- $ref: "#/components/schemas/Folder"
- $ref: "#/components/schemas/WebLink"
- description: The item that was recently accessed.
type:
description: "`recent_item`"
example: recent_item
type: string
title: Recent item
type: object
x-box-resource-id: recent_item
x-box-tag: recent_items
RecentItems:
allOf:
- description: |-
The part of an API response that describes marker
based pagination
properties:
limit:
description: |-
The limit that was used for these entries. This will be the same as the
`limit` query parameter unless that value exceeded the maximum value
allowed. The maximum value varies by API.
example: 1000
format: int64
type: integer
next_marker:
description: The marker for the start of the next page of results.
example: 3000
format: int64
type: integer
prev_marker:
description: The marker for the start of the previous page of results.
example: 1000
format: int64
type: integer
type: object
- properties:
entries:
items:
$ref: "#/components/schemas/RecentItem"
type: array
description: A list of recent items.
title: Recent items
type: object
x-box-resource-id: recent_items
RetentionPolicies:
allOf:
- properties:
entries:
description: A list in which each entry represents a retention policy object.
items:
$ref: "#/components/schemas/RetentionPolicy--Mini"
type: array
- description: |-
The part of an API response that describes marker
based pagination
properties:
limit:
description: |-
The limit that was used for these entries. This will be the same as the
`limit` query parameter unless that value exceeded the maximum value
allowed. The maximum value varies by API.
example: 1000
format: int64
type: integer
next_marker:
description: The marker for the start of the next page of results.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
type: string
type: object
description: A list of retention policies.
title: Retention policies
type: object
x-box-resource-id: retention_policies
x-box-tag: retention_policies
RetentionPolicy:
allOf:
- $ref: "#/components/schemas/RetentionPolicy--Mini"
- properties:
are_owners_notified:
description: |-
Determines if owners and co-owners of items
under the policy are notified when
the retention duration is about to end.
example: false
type: boolean
assignment_counts:
description: Counts the retention policy assignments for each item type.
properties:
enterprise:
description: The number of enterprise assignments this policy has. The maximum value is 1.
example: 1
format: int64
type: integer
folder:
description: The number of folder assignments this policy has.
example: 1
format: int64
type: integer
metadata_template:
description: The number of metadata template assignments this policy has.
example: 1
format: int64
type: integer
type: object
can_owner_extend_retention:
description: |-
Determines if the owner of items under the policy
can extend the retention when the original
retention duration is about to end.
example: false
type: boolean
created_at:
description: When the retention policy object was created.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
created_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: |-
A mini user object representing the user that
created the retention policy.
custom_notification_recipients:
description: A list of users notified when the retention policy duration is about to end.
items:
$ref: "#/components/schemas/User--Mini"
type: array
description:
description: The additional text description of the retention policy.
example: Policy to retain all reports for at least one month
type: string
modified_at:
description: When the retention policy object was last modified.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
policy_type:
description: |-
The type of the retention policy. A retention
policy type can either be `finite`, where a
specific amount of time to retain the content is known
upfront, or `indefinite`, where the amount of time
to retain the content is still unknown.
enum:
- finite
- indefinite
example: finite
type: string
retention_type:
description: |-
Specifies the retention type:
* `modifiable`: You can modify the retention policy. For example,
you can add or remove folders, shorten or lengthen
the policy duration, or delete the assignment.
Use this type if your retention policy
is not related to any regulatory purposes.
* `non-modifiable`: You can modify the retention policy
only in a limited way: add a folder, lengthen the duration,
retire the policy, change the disposition action
or notification settings. You cannot perform other actions,
such as deleting the assignment or shortening the
policy duration. Use this type to ensure
compliance with regulatory retention policies.
enum:
- modifiable
- non-modifiable
example: non-modifiable
type: string
status:
description: |-
The status of the retention policy. The status of
a policy will be `active`, unless explicitly retired by an
administrator, in which case the status will be `retired`.
Once a policy has been retired, it cannot become
active again.
enum:
- active
- retired
example: active
type: string
description: |-
A retention policy blocks permanent deletion of content
for a specified amount of time. Admins can create retention
policies and then later assign them to specific folders, metadata
templates, or their entire enterprise. To use this feature, you must
have the manage retention policies scope enabled
for your API key via your application management console.
title: Retention policy
type: object
x-box-resource-id: retention_policy
x-box-tag: retention_policies
x-box-variant: standard
RetentionPolicy--Base:
description: A base representation of a retention policy.
properties:
id:
description: The unique identifier that represents a retention policy.
example: "12345"
nullable: false
type: string
type:
description: "`retention_policy`"
enum:
- retention_policy
example: retention_policy
nullable: false
type: string
required:
- id
- type
title: Retention policy (Base)
type: object
x-box-resource-id: retention_policy--base
x-box-tag: retention_policies
x-box-variant: base
x-box-variants:
- base
- mini
- standard
RetentionPolicy--Mini:
allOf:
- $ref: "#/components/schemas/RetentionPolicy--Base"
- properties:
disposition_action:
description: |-
The disposition action of the retention policy.
This action can be `permanently_delete`, which
will cause the content retained by the policy
to be permanently deleted, or `remove_retention`,
which will lift the retention policy from the content,
allowing it to be deleted by users,
once the retention policy has expired.
enum:
- permanently_delete
- remove_retention
example: permanently_delete
type: string
policy_name:
description: The name given to the retention policy.
example: Some Policy Name
type: string
retention_length:
description: |-
The length of the retention policy. This value
specifies the duration in days that the retention
policy will be active for after being assigned to
content. If the policy has a `policy_type` of
`indefinite`, the `retention_length` will also be
`indefinite`.
example: "365"
format: int32
minimum: 1
type: string
description: |-
A mini representation of a retention policy, used when
nested within another resource.
title: Retention policy (Mini)
type: object
x-box-resource-id: retention_policy--mini
x-box-variant: mini
RetentionPolicyAssignment:
description: |-
A retention assignment represents a rule specifying
the files a retention policy retains.
Assignments can retain files based on their folder or metadata,
or hold all files in the enterprise.
properties:
assigned_at:
description: |-
When the retention policy assignment object was
created.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
assigned_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: |-
A mini user object representing the user that
created the retention policy assignment.
assigned_to:
description: |-
The `type` and `id` of the content that is under
retention. The `type` can either be `folder`
`enterprise`, or `metadata_template`.
properties:
id:
description: |-
The ID of the folder, enterprise, or metadata template
the policy is assigned to.
example: a983f69f-e85f-4ph4-9f46-4afdf9c1af65
type: string
type:
description: The type of resource the policy is assigned to.
enum:
- folder
- enterprise
- metadata_template
example: metadata_template
type: string
type: object
filter_fields:
description: |-
An array of field objects. Values are only returned if the `assigned_to`
type is `metadata_template`. Otherwise, the array is blank.
items:
nullable: true
properties:
field:
description: The metadata attribute key id.
example: a0f4ee4e-1dc1-4h90-a8a9-aef55fc681d4
nullable: true
type: string
value:
description: |-
The metadata attribute field id. For value, only
enum and multiselect types are supported.
example: 0c27b756-0p87-4fe0-a43a-59fb661ccc4e
nullable: true
type: string
type: object
nullable: true
type: array
id:
description: The unique identifier for a retention policy assignment.
example: "11446498"
type: string
retention_policy:
allOf:
- $ref: "#/components/schemas/RetentionPolicy--Mini"
- description: |-
A mini representation of a retention policy object
that has been assigned to the content.
start_date_field:
description: |-
The date the retention policy assignment begins.
If the `assigned_to` type is `metadata_template`,
this field can be a date field's metadata attribute key id.
example: upload_date
type: string
type:
description: "`retention_policy_assignment`"
enum:
- retention_policy_assignment
example: retention_policy_assignment
type: string
title: Retention policy assignment
type: object
x-box-resource-id: retention_policy_assignment
x-box-tag: retention_policy_assignments
RetentionPolicyAssignment--Base:
description: A base representation of a retention policy assignment.
properties:
id:
description: The unique identifier that represents a file version.
example: "12345"
nullable: false
type: string
type:
description: "`retention_policy_assignment`"
enum:
- retention_policy_assignment
example: retention_policy_assignment
nullable: false
type: string
required:
- id
- type
title: Retention policy assignment (Base)
type: object
x-box-resource-id: retention_policy_assignment--base
x-box-tag: retention_policy_assignments
x-box-variant: base
x-box-variants:
- base
- standard
RetentionPolicyAssignments:
allOf:
- properties:
entries:
items:
$ref: "#/components/schemas/RetentionPolicyAssignment--Base"
type: array
- description: |-
The part of an API response that describes marker
based pagination
properties:
limit:
description: |-
The limit that was used for these entries. This will be the same as the
`limit` query parameter unless that value exceeded the maximum value
allowed. The maximum value varies by API.
example: 1000
format: int64
type: integer
next_marker:
description: The marker for the start of the next page of results.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
type: string
type: object
description: A list of retention policy assignments.
title: Retention policy assignments
type: object
x-box-resource-id: retention_policy_assignments
x-box-tag: retention_policy_assignments
SearchResultWithSharedLink:
description: |-
A single of files, folder or web link that matched the search query,
including the additional information about the shared link through
which the item has been shared with the user.
This response format is only returned when the
`include_recent_shared_links` query parameter has been set to `true`.
properties:
accessible_via_shared_link:
description: |-
The optional shared link through which the user has access to this
item. This value is only returned for items for which the user has
recently accessed the file through a shared link. For all other
items this value will return `null`.
example: https://www.box.com/s/vspke7y05sb214wjokpk
format: url
type: string
item:
allOf:
- oneOf:
- $ref: "#/components/schemas/File"
- $ref: "#/components/schemas/Folder"
- $ref: "#/components/schemas/WebLink"
- description: |-
The file, folder or web link that matched the
search query.
type:
description: The result type. The value is always `search_result`.
example: search_result
type: string
title: Search Result (including Shared Link)
type: object
x-box-resource-id: search_result_with_shared_link
x-box-tag: search
SearchResults:
allOf:
- properties:
limit:
description: |-
The limit that was used for this search. This will be the same as the
`limit` query parameter unless that value exceeded the maximum value
allowed.
example: 1000
format: int64
type: integer
offset:
description: |-
The 0-based offset of the first entry in this set. This will be the same
as the `offset` query parameter used.
example: 2000
format: int64
type: integer
total_count:
description: |-
One greater than the offset of the last entry in the search results.
The total number of entries in the collection may be less than
`total_count`.
example: 5000
format: int64
type: integer
type: object
- properties:
entries:
description: The search results for the query provided.
items:
oneOf:
- $ref: "#/components/schemas/File"
- $ref: "#/components/schemas/Folder"
- $ref: "#/components/schemas/WebLink"
type: array
description: A list of files, folders and web links that matched the search query.
title: Search Results
type: object
x-box-resource-id: search_results
x-box-tag: search
SearchResultsWithSharedLinks:
allOf:
- properties:
limit:
description: |-
The limit that was used for this search. This will be the same as the
`limit` query parameter unless that value exceeded the maximum value
allowed.
example: 1000
format: int64
type: integer
offset:
description: |-
The 0-based offset of the first entry in this set. This will be the same
as the `offset` query parameter used.
example: 2000
format: int64
type: integer
total_count:
description: |-
One greater than the offset of the last entry in the search results.
The total number of entries in the collection may be less than
`total_count`.
example: 5000
format: int64
type: integer
type: object
- properties:
entries:
description: |-
The search results for the query provided, including the
additional information about any shared links through
which the item has been shared with the user.
items:
$ref: "#/components/schemas/SearchResultWithSharedLink"
type: array
description: |-
A list of files, folders and web links that matched the search query,
including the additional information about any shared links through
which the item has been shared with the user.
This response format is only returned when the `include_recent_shared_links`
query parameter has been set to `true`.
title: Search Results (including Shared Links)
type: object
x-box-resource-id: search_results_with_shared_links
x-box-tag: search
SessionTerminationMessage:
description: |-
A message informing about the
termination job status
properties:
message:
description: The unique identifier for the termination job status
example: Request is successful, please check the admin events for the status of the job
type: string
title: Session termination message
type: object
x-box-resource-id: session_termination
x-box-tag: session_termination
ShieldInformationBarrier:
description: |-
A standard representation of a
shield information barrier object
properties:
created_at:
description: |-
ISO date time string when this
shield information barrier object was created.
example: 2020-06-26T18:44:45.869Z
format: date-time
type: string
created_by:
allOf:
- $ref: "#/components/schemas/User--Base"
- description: The user who created this shield information barrier.
enabled_at:
description: ISO date time string when this shield information barrier was enabled.
example: 2020-07-26T18:44:45.869Z
format: date-time
type: string
enabled_by:
allOf:
- $ref: "#/components/schemas/User--Base"
- description: The user that enabled this shield information barrier.
enterprise:
allOf:
- $ref: "#/components/schemas/Enterprise--Base"
- description: The `type` and `id` of enterprise this barrier is under.
id:
description: The unique identifier for the shield information barrier
example: "11446498"
type: string
status:
description: Status of the shield information barrier
enum:
- draft
- pending
- disabled
- enabled
- invalid
example: draft
type: string
type:
description: The type of the shield information barrier
enum:
- shield_information_barrier
example: shield_information_barrier
type: string
updated_at:
description: ISO date time string when this shield information barrier was updated.
example: 2020-07-26T18:44:45.869Z
format: date-time
type: string
updated_by:
allOf:
- $ref: "#/components/schemas/User--Base"
- description: The user that updated this shield information barrier.
title: Shield information barrier
type: object
x-box-resource-id: shield_information_barrier
x-box-tag: shield_information_barriers
x-box-variant: standard
x-box-variants:
- base
- standard
ShieldInformationBarrier--Base:
description: |-
A base representation of a
shield information barrier object
properties:
id:
description: The unique identifier for the shield information barrier
example: "11446498"
type: string
type:
description: The type of the shield information barrier
enum:
- shield_information_barrier
example: shield_information_barrier
type: string
title: Shield information barrier (Base)
type: object
x-box-resource-id: shield_information_barrier--base
x-box-tag: shield_information_barriers
x-box-variant: base
x-box-variants:
- base
- standard
ShieldInformationBarrierReference:
description: A shield information barrier reference for requests and responses
properties:
shield_information_barrier:
$ref: "#/components/schemas/ShieldInformationBarrier--Base"
title: Shield information barrier reference
type: object
x-box-resource-id: shield_information_barrier_reference
x-box-tag: shield_information_barrier_reports
ShieldInformationBarrierReport:
allOf:
- $ref: "#/components/schemas/ShieldInformationBarrierReport--Base"
- properties:
created_at:
description: |-
ISO date time string when this
shield information barrier report object was created.
example: 2020-06-26T18:44:45.869Z
format: date-time
type: string
created_by:
allOf:
- $ref: "#/components/schemas/User--Base"
- description: The user who created this shield information barrier report.
details:
allOf:
- $ref: "#/components/schemas/ShieldInformationBarrierReportDetails"
shield_information_barrier:
allOf:
- $ref: "#/components/schemas/ShieldInformationBarrierReference"
status:
description: Status of the shield information report
enum:
- pending
- error
- done
- cancelled
example: pending
type: string
updated_at:
description: |-
ISO date time string when this
shield information barrier report was updated.
example: 2020-07-26T18:44:45.869Z
format: date-time
type: string
description: |-
A standard representation
of a shield information barrier report object
title: Shield information barrier report
type: object
x-box-resource-id: shield_information_barrier_report
x-box-tag: shield_information_barrier_reports
x-box-variant: standard
x-box-variants:
- base
- standard
ShieldInformationBarrierReport--Base:
description: |-
A base representation of a
shield information barrier report object
properties:
id:
description: The unique identifier for the shield information barrier report
example: "11446498"
type: string
type:
description: The type of the shield information barrier report
enum:
- shield_information_barrier_report
example: shield_information_barrier_report
type: string
title: Shield information barrier report (Base)
type: object
x-box-resource-id: shield_information_barrier_report--base
x-box-tag: shield_information_barrier_reports
x-box-variant: base
x-box-variants:
- base
- standard
ShieldInformationBarrierReportDetails:
description: |-
Indicates which folder the report
file is located and any errors when generating the report.
properties:
details:
properties:
folder_id:
description: Folder ID for locating this report
example: "124235"
type: string
type: object
title: Shield information barrier report details
type: object
x-box-resource-id: shield_information_barrier_report_details
x-box-tag: shield_information_barrier_reports
ShieldInformationBarrierSegment:
description: A shield information barrier segment object
properties:
created_at:
description: |-
ISO date time string when this shield information
barrier object was created.
example: 2020-06-26T18:44:45.869Z
format: date-time
type: string
created_by:
allOf:
- $ref: "#/components/schemas/User--Base"
- description: The user who created this shield information barrier segment.
description:
description: Description of the shield information barrier segment
example: |-
'Corporate division that engages in advisory_based financial
transactions on behalf of individuals, corporations, and governments.'
type: string
id:
description: The unique identifier for the shield information barrier segment
example: "11446498"
type: string
name:
description: Name of the shield information barrier segment
example: Investment Banking
type: string
shield_information_barrier:
$ref: "#/components/schemas/ShieldInformationBarrier--Base"
type:
description: The type of the shield information barrier segment
enum:
- shield_information_barrier_segment
example: shield_information_barrier_segment
type: string
updated_at:
description: |-
ISO date time string when this
shield information barrier segment was updated.
example: 2020-07-26T18:44:45.869Z
format: date-time
type: string
updated_by:
allOf:
- $ref: "#/components/schemas/User--Base"
- description: The user that updated this shield information barrier segment.
title: Shield information barrier segment
type: object
x-box-resource-id: shield_information_barrier_segment
x-box-tag: shield_information_barrier_segments
ShieldInformationBarrierSegmentMember:
allOf:
- $ref: "#/components/schemas/ShieldInformationBarrierSegmentMember--Mini"
- properties:
created_at:
description: |-
ISO date time string when this shield
information barrier object was created.
example: 2020-06-26T18:44:45.869Z
format: date-time
type: string
created_by:
allOf:
- $ref: "#/components/schemas/User--Base"
- description: The user who created this shield information barrier segment member.
shield_information_barrier:
$ref: "#/components/schemas/ShieldInformationBarrier--Base"
shield_information_barrier_segment:
description: |-
The `type` and `id` of the requested
shield information barrier segment.
properties:
id:
description: |-
The ID reference of the requesting
shield information barrier segment.
example: "432554"
type: string
type:
description: The type of the shield information barrier segment
enum:
- shield_information_barrier_segment
example: shield_information_barrier_segment
type: string
type: object
updated_at:
description: |-
ISO date time string when this
shield information barrier segment Member was updated.
example: 2020-07-26T18:44:45.869Z
format: date-time
type: string
updated_by:
allOf:
- $ref: "#/components/schemas/User--Base"
- description: The user that updated this shield information barrier segment Member.
user:
allOf:
- $ref: "#/components/schemas/User--Base"
- description: The `type` and `id` of the requested shield information barrier segment member.
description: |-
A standard representation of a
shield information barrier segment member object
title: Shield information barrier segment member
type: object
x-box-resource-id: shield_information_barrier_segment_member
x-box-tag: shield_information_barrier_segment_members
x-box-variant: standard
x-box-variants:
- base
- mini
- standard
ShieldInformationBarrierSegmentMember--Base:
description: |-
A base representation of a
shield information barrier segment member object
properties:
id:
description: |-
The unique identifier for the
shield information barrier segment member
example: "11446498"
type: string
type:
description: The type of the shield information barrier segment member
enum:
- shield_information_barrier_segment_member
example: shield_information_barrier_segment_member
type: string
title: Shield information barrier segment member (Base)
type: object
x-box-resource-id: shield_information_barrier_segment_member--base
x-box-tag: shield_information_barrier_segment_members
x-box-variant: base
x-box-variants:
- base
- mini
- standard
ShieldInformationBarrierSegmentMember--Mini:
allOf:
- $ref: "#/components/schemas/ShieldInformationBarrierSegmentMember--Base"
- properties:
user:
allOf:
- $ref: "#/components/schemas/User--Base"
- description: The `type` and `id` of the requested shield information barrier segment member.
description: |-
A mini representation of a
shield information barrier segment member object
title: Shield information barrier segment member (Mini)
type: object
x-box-resource-id: shield_information_barrier_segment_member--mini
x-box-tag: shield_information_barrier_segment_members
x-box-variant: mini
x-box-variants:
- base
- mini
- standard
ShieldInformationBarrierSegmentRestriction:
allOf:
- $ref: "#/components/schemas/ShieldInformationBarrierSegmentRestriction--Mini"
- properties:
created_at:
description: |-
ISO date time string when this
shield information barrier
Segment Restriction object was created.
example: 2020-06-26T18:44:45.869Z
format: date-time
type: string
created_by:
allOf:
- $ref: "#/components/schemas/User--Base"
- description: The user who created this shield information barrier segment Restriction.
shield_information_barrier:
$ref: "#/components/schemas/ShieldInformationBarrier--Base"
updated_at:
description: |-
ISO date time string when this
shield information barrier segment
Restriction was updated.
example: 2020-07-26T18:44:45.869Z
format: date-time
type: string
updated_by:
allOf:
- $ref: "#/components/schemas/User--Base"
- description: The user that updated this shield information barrier segment Restriction.
description: |-
A standard representation of a
segment restriction of a shield information barrier
object
required:
- shield_information_barrier_segment
- restricted_segment
title: Shield information barrier segment restriction
type: object
x-box-resource-id: shield_information_barrier_segment_restriction
x-box-tag: shield_information_barrier_segment_restrictions
x-box-variant: standard
x-box-variants:
- base
- mini
- standard
ShieldInformationBarrierSegmentRestriction--Base:
description: |-
A base representation of
a segment restriction object for
the shield information barrier
properties:
id:
description: |-
The unique identifier for the
shield information barrier segment restriction.
example: "11446498"
type: string
type:
description: Shield information barrier segment restriction
enum:
- shield_information_barrier_segment_restriction
example: shield_information_barrier_segment_restriction
type: string
required:
- shield_information_barrier_segment
- restricted_segment
title: Shield information barrier segment restriction (Base)
type: object
x-box-resource-id: shield_information_barrier_segment_restriction--base
x-box-tag: shield_information_barrier_segment_restrictions
x-box-variant: base
x-box-variants:
- base
- mini
- standard
ShieldInformationBarrierSegmentRestriction--Mini:
allOf:
- $ref: "#/components/schemas/ShieldInformationBarrierSegmentRestriction--Base"
- properties:
restricted_segment:
description: |-
The `type` and `id` of the
restricted shield information barrier segment.
properties:
id:
description: |-
The ID reference of the
restricted shield information barrier segment.
example: "1910967"
type: string
type:
description: The type of the shield information segment
enum:
- shield_information_barrier_segment
example: shield_information_barrier_segment
type: string
type: object
shield_information_barrier_segment:
description: |-
The `type` and `id` of the
requested shield information barrier segment.
properties:
id:
description: |-
The ID reference of the
requesting shield information barrier segment.
example: "1910967"
type: string
type:
description: The type of the shield information barrier segment
enum:
- shield_information_barrier_segment
example: shield_information_barrier_segment
type: string
type: object
description: |-
A mini representation of
a segment restriction object for
the shield information barrier
required:
- shield_information_barrier_segment
- restricted_segment
title: Shield information barrier segment restriction (Mini)
type: object
x-box-resource-id: shield_information_barrier_segment_restriction--mini
x-box-tag: shield_information_barrier_segment_restrictions
x-box-variant: mini
x-box-variants:
- base
- mini
- standard
SignRequest:
allOf:
- $ref: "#/components/schemas/SignRequest--Base"
- properties:
auto_expire_at:
description: Uses `days_valid` to calculate the date and time, in GMT, the sign request will expire if unsigned.
example: 2021-04-26T08:12:13.982Z
format: date-time
nullable: true
type: string
id:
description: Sign request ID
example: "12345"
type: string
prepare_url:
description: |-
This URL is returned if `is_document_preparation_needed` is
set to `true` in the request. It is used to prepare the sign request
via UI. The sign request is not sent until preparation is complete.
example: https://prepareurl.com
nullable: true
type: string
sign_files:
description: |-
List of files that will be signed, which are copies of the original
source files. A new version of these files are created as signers sign
and can be downloaded at any point in the signing process.
properties:
files:
items:
$ref: "#/components/schemas/File--Mini"
type: array
is_ready_for_download:
description: |-
Indicates whether the `sign_files` documents are processing
and the PDFs may be out of date. A change to any document
requires processing on all `sign_files`. We
recommended waiting until processing is finished
(and this value is true) before downloading the PDFs.
example: true
type: boolean
type: object
signature_color:
description: Force a specific color for the signature (blue, black, or red).
example: blue
nullable: true
type: string
signers:
description: Array of signers for the sign request
items:
$ref: "#/components/schemas/SignRequestSigner"
type: array
signing_log:
allOf:
- $ref: "#/components/schemas/File--Mini"
- description: |-
Reference to a file that holds a log of all signer activity for
the request
source_files:
description: List of files to create a signing document from. Only the ID and type fields are required for each file. The array will be empty if the `source_files` are deleted.
items:
$ref: "#/components/schemas/File--Mini"
type: array
status:
description: Describes the status of the sign request
enum:
- converting
- created
- sent
- viewed
- signed
- cancelled
- declined
- error_converting
- error_sending
- expired
example: converting
type: string
type:
description: object type
enum:
- sign-request
example: sign-request
type: string
description: A Sign Request Object
title: Sign Request
type: object
x-box-resource-id: sign_request
x-box-tag: sign_requests
SignRequest--Base:
description: A request to create a sign request object
properties:
are_reminders_enabled:
description: Reminds signers to sign a document on day 3, 8, 13 and 18. Reminders are only sent to outstanding signers.
example: true
type: boolean
are_text_signatures_enabled:
default: true
description: Disables the usage of signatures generated by typing (text).
example: true
type: boolean
days_valid:
description: Number of days after which this request will automatically expire if not completed.
example: 2
maximum: 730
minimum: 0
nullable: true
type: integer
declined_redirect_url:
description: The uri that a signer will be redirected to after declining to sign a document.
example: https://declined-redirect.com
nullable: true
type: string
email_message:
description: Message to include in sign request email. The field is cleaned through sanitization of specific characters. However, some html tags are allowed. Links included in the message are also converted to hyperlinks in the email. The message may contain the following html tags including `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. If this field is not passed, a default message will be used.
example: Hello! Please sign the document below
nullable: true
type: string
email_subject:
description: Subject of sign request email. This is cleaned by sign request. If this field is not passed, a default subject will be used.
example: Sign Request from Acme
nullable: true
type: string
external_id:
description: This can be used to reference an ID in an external system that the sign request is related to.
example: "123"
nullable: true
type: string
is_document_preparation_needed:
description: Indicates if the sender should receive a `prepare_url` in the response to complete document preparation via UI.
example: true
type: boolean
is_phone_verification_required_to_view:
description: Forces signers to verify a text message prior to viewing the document. You must specify the phone number of signers to have this setting apply to them.
example: true
nullable: true
type: boolean
name:
description: Name of the sign request.
example: name
type: string
parent_folder:
allOf:
- $ref: "#/components/schemas/Folder--Mini"
- description: |-
The destination folder to place final, signed document and signing
log. Only `ID` and `type` fields are required. The root folder,
folder ID `0`, cannot be used.
prefill_tags:
description: When a document contains sign related tags in the content, you can prefill them using this `prefill_tags` by referencing the 'id' of the tag as the `external_id` field of the prefill tag.
items:
$ref: "#/components/schemas/SignRequestPrefillTag"
type: array
redirect_url:
description: When specified, signature request will be redirected to this url when a document is signed.
example: https://www.example.com
nullable: true
type: string
required:
- source_files
- parent_folder
title: Create a sign request
type: object
x-box-resource-id: sign_request--base
x-box-tag: sign_requests
SignRequestCreateRequest:
allOf:
- $ref: "#/components/schemas/SignRequest--Base"
- properties:
signature_color:
description: Force a specific signature color (blue, black, or red).
enum:
- blue
- black
- red
example: blue
nullable: true
type: string
signers:
description: |-
Array of signers for the sign request. 35 is the
max number of signers permitted.
items:
$ref: "#/components/schemas/SignRequestCreateSigner"
type: array
source_files:
description: |-
List of files to create a signing document from. This is currently
limited to 10 files. Only the ID and type fields are required
for each file. The array will be empty if the `source_files`
are deleted.
items:
$ref: "#/components/schemas/File--Mini"
maximum: 10
minimum: 1
type: array
description: A request to create a sign request object
required:
- signers
title: Create a sign request
type: object
SignRequestCreateSigner:
description: The schema for a Signer in a POST Sign Request request body
properties:
declined_redirect_url:
description: |-
The URL that a signer will be redirect
to after declining to sign a document.
Defining this URL overrides default or global
declined redirect URL settings for a specific signer.
example: https://declined-example.com
nullable: true
type: string
email:
description: Email address of the signer
example: example@gmail.com
type: string
embed_url_external_user_id:
description: |-
User ID for the signer in an external application responsible
for authentication when accessing the embed URL.
example: "1234"
type: string
is_in_person:
description: |-
Used in combination with an embed URL for a sender. After the
sender signs, they are redirected to the next `in_person` signer.
example: true
type: boolean
login_required:
description: |-
If set to true, signer will need to login to a Box account
before signing the request. If the signer does not have
an existing account, they will have an option to create
a free Box account.
example: true
nullable: true
type: boolean
order:
description: Order of the signer
example: 2
minimum: 0
type: integer
password:
description: |-
If set, the signer is required to enter the password before they are able
to sign a document. This field is write only.
example: SecretPassword123
type: string
writeOnly: true
redirect_url:
description: |-
The URL that a signer will be redirected
to after signing a document. Defining this URL
overrides default or global redirect URL
settings for a specific signer.
If no declined redirect URL is specified,
this URL will be used for decline actions as well.
example: https://example.com
nullable: true
type: string
role:
default: signer
description: |-
Defines the role of the signer in the sign request. A `signer`
must sign the document and an `approver` must approve the document. A
`final_copy_reader` only receives the final signed document and signing
log.
enum:
- signer
- approver
- final_copy_reader
example: signer
type: string
verification_phone_number:
description: |-
If set, this phone number is be used to verify the signer
via two factor authentication before they are able to sign the document.
example: "6314578901"
type: string
required:
- email
title: Signer fields for Create Sign Request
type: object
SignRequestPrefillTag:
description: |-
Prefill tags are used to prefill placeholders with signer input data. Only
one value field can be included.
properties:
checkbox_value:
description: Checkbox prefill value
example: true
type: boolean
date_value:
description: Date prefill value
example: 2021-04-26T08:12:13.982Z
format: date-time
type: string
document_tag_id:
description: This references the ID of a specific tag contained in a file of the sign request.
example: "1234"
type: string
text_value:
description: Text prefill value
example: text
type: string
title: Sign Request Prefill Tag
type: object
SignRequestSigner:
allOf:
- $ref: "#/components/schemas/SignRequestCreateSigner"
- properties:
embed_url:
description: URL to direct a signer to for signing
example: https://example.com
readOnly: true
type: string
has_viewed_document:
description: Set to `true` if the signer views the document
example: true
readOnly: true
type: boolean
inputs:
items:
$ref: "#/components/schemas/SignRequestSignerInput"
readOnly: true
type: array
signer_decision:
description: Final decision made by the signer
properties:
finalized_at:
description: Date and Time that the decision was made
example: 2021-04-26T08:12:13.982Z
format: date-time
type: string
type:
description: Type of decision made by the signer
enum:
- signed
- declined
example: signed
type: string
type: object
description: The schema for a Signer in a GET Sign Request request body
required:
- email
title: Signer fields for GET Sign Request response
type: object
SignRequestSignerInput:
allOf:
- $ref: "#/components/schemas/SignRequestPrefillTag"
- properties:
content_type:
description: Content type of input
enum:
- initial
- stamp
- signature
- company
- title
- email
- full_name
- first_name
- last_name
- text
- date
- checkbox
- attachment
example: signature
type: string
page_index:
description: Index of page that the input is on
example: 4
type: integer
type:
description: Type of input
enum:
- signature
- date
- text
- checkbox
example: text
type: string
description: Input created by a Signer on a Sign Request
required:
- page_index
title: Sign Request Signer Input
type: object
SignRequests:
allOf:
- description: |-
The part of an API response that describes marker
based pagination
properties:
limit:
description: |-
The limit that was used for these entries. This will be the same as the
`limit` query parameter unless that value exceeded the maximum value
allowed. The maximum value varies by API.
example: 1000
format: int64
type: integer
next_marker:
description: The marker for the start of the next page of results.
example: 3000
format: int64
type: integer
prev_marker:
description: The marker for the start of the previous page of results.
example: 1000
format: int64
type: integer
type: object
- properties:
entries:
items:
$ref: "#/components/schemas/SignRequest"
type: array
description: |-
A standard representation of a sign request, as returned from any Box Sign
API endpoints by default.
title: Sign Requests
type: object
x-box-resource-id: sign_requests
x-box-tag: sign_requests
SkillCardsMetadata:
description: The metadata assigned to a using for Box skills.
properties:
$canEdit:
description: Whether the user can edit this metadata
example: true
type: boolean
$id:
description: A UUID to identify the metadata object
example: 01234500-12f1-1234-aa12-b1d234cb567e
format: uuid
maxLength: 36
type: string
$parent:
description: An ID for the parent folder
example: folder_59449484661,
type: string
$scope:
description: |-
An ID for the scope in which this template
has been applied
example: enterprise_27335
type: string
$template:
description: The name of the template
example: properties
type: string
$type:
description: |-
A unique identifier for the "type" of this instance. This is an internal
system property and should not be used by a client application.
example: properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0
type: string
$typeVersion:
description: |-
The last-known version of the template of the object. This is an internal
system property and should not be used by a client application.
example: 2
type: integer
$version:
description: |-
The version of the metadata object. Starts at 0 and increases every time
a user-defined property is modified.
example: 1
type: integer
cards:
description: A list of Box Skill cards that have been applied to this file.
items:
oneOf:
- $ref: "#/components/schemas/KeywordSkillCard"
- $ref: "#/components/schemas/TimelineSkillCard"
- $ref: "#/components/schemas/TranscriptSkillCard"
- $ref: "#/components/schemas/StatusSkillCard"
type: array
title: Skills metadata instance
type: object
x-box-resource-id: skill_cards_metadata
x-box-tag: skills
SkillInvocation:
description: |-
The payload of a Box skill as sent to a skill's
`invocation_url`.
properties:
created_at:
description: The time this invocation was created.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
enterprise:
allOf:
- description: A representation of a Box enterprise
properties:
id:
description: The unique identifier for this enterprise.
example: "11446498"
type: string
name:
description: The name of the enterprise
example: Acme Inc.
type: string
type:
description: "`enterprise`"
enum:
- enterprise
example: enterprise
type: string
title: Enterprise
type: object
- description: The enterprise that this invocation was triggered for
event:
allOf:
- $ref: "#/components/schemas/Event"
- description: The event that triggered this invocation
id:
description: Unique identifier for the invocation request.
example: fd1d2e53-35f5-41fb-9c25-4ba326daf2f9_341016304
type: string
skill:
allOf:
- description: An object representing a skill
properties:
api_key:
description: The client ID of the application
example: hxel2s12wd2h9r8ne103c4gjbqefofih
type: string
id:
description: The unique identifier for this skill
example: "11446498"
type: string
name:
description: The name of the skill
example: Hello World Skill
type: string
type:
description: "`skill`"
enum:
- skill
example: skill
type: string
title: Skill
type: object
- description: The skill that triggered this invocation
source:
allOf:
- oneOf:
- $ref: "#/components/schemas/File"
- $ref: "#/components/schemas/Folder"
- description: The item that caused the invocation to trigger
status:
description: The details status of this event.
properties:
additional_info:
description: Additional status information.
example: Example
type: string
error_code:
description: Error code information, if error occurred.
example: "400"
type: string
message:
description: Status information
example: Example
type: string
state:
description: |-
The state of this event.
* `invoked` - Triggered the skill with event details to start
applying skill on the file.
* `processing` - Currently processing.
* `success` - Completed processing with a success.
* `transient_failure` - Encountered an issue which can be
retried.
* `permanent_failure` - Encountered a permanent issue and
retry would not help.
enum:
- invoked
- processing
- success
- transient_failure
- permanent_failure
example: invoked
type: string
type: object
token:
description: The read-only and read-write access tokens for this item
properties:
read:
description: The basics of an access token
properties:
access_token:
description: The requested access token.
example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ
format: token
type: string
expires_in:
description: The time in seconds in seconds by which this token will expire.
example: 3600
format: int64
type: integer
restricted_to:
description: |-
The permissions that this access token permits,
providing a list of resources (files, folders, etc)
and the scopes permitted for each of those resources.
example: '[{"scope":"gcm"}, {"scope":"item_upload","object_id":933941692081,"object_type":"file"}, {"scope":"manage_skill_invocations"}]'
type: string
token_type:
description: The type of access token returned.
enum:
- bearer
example: bearer
type: string
type: object
write:
description: The basics of an access token
properties:
access_token:
description: The requested access token.
example: c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ
format: token
type: string
expires_in:
description: The time in seconds in seconds by which this token will expire.
example: 3600
format: int64
type: integer
restricted_to:
description: |-
The permissions that this access token permits,
providing a list of resources (files, folders, etc)
and the scopes permitted for each of those resources.
example: '[{"scope":"gcm"}, {"scope":"item_upload","object_id":933941692081,"object_type":"file"}, {"scope":"manage_skill_invocations"}]'
type: string
token_type:
description: The type of access token returned.
enum:
- bearer
example: bearer
type: string
type: object
type: object
trigger:
description: Action that triggered the invocation
example: FILE_CONTENT
type: string
type:
description: "`skill_invocation`"
enum:
- skill_invocation
example: skill_invocation
type: string
title: Skill webhook payload
type: object
x-box-resource-id: skill_invocation
x-box-tag: skills
StatusSkillCard:
description: A Box Skill metadata card that puts a status message in the metadata sidebar.
properties:
created_at:
description: The optional date and time this card was created at.
example: 2018-04-13T13:53:23-07:00
format: date-time
type: string
invocation:
description: |-
The invocation of this service, used to track
which instance of a service applied the metadata.
properties:
id:
description: |-
A custom identifier that represent the instance of
the service that applied this metadata. For example,
if your `image-recognition-service` runs on multiple
nodes, this field can be used to identify the ID of
the node that was used to apply the metadata.
example: image-recognition-service-123
type: string
type:
description: "`skill_invocation`"
enum:
- skill_invocation
example: skill_invocation
type: string
required:
- type
- id
type: object
skill:
description: The service that applied this metadata.
properties:
id:
description: |-
A custom identifier that represent the service that
applied this metadata.
example: image-recognition-service
type: string
type:
description: "`service`"
enum:
- service
example: service
type: string
required:
- type
- id
type: object
skill_card_title:
description: The title of the card.
properties:
code:
description: An optional identifier for the title.
example: status
type: string
message:
description: The actual title to show in the UI.
example: Status
type: string
required:
- message
type: object
skill_card_type:
description: "`status`"
enum:
- status
example: status
type: string
status:
description: Sets the status of the skill. This can be used to show a message to the user while the Skill is processing the data, or if it was not able to process the file.
properties:
code:
description: |-
A code for the status of this Skill invocation. By
default each of these will have their own accompanied
messages. These can be adjusted by setting the `message`
value on this object.
enum:
- invoked
- processing
- success
- transient_failure
- permanent_failure
example: success
type: string
message:
description: |-
A custom message that can be provided with this status.
This will be shown in the web app to the end user.
example: We're preparing to process your file. Please hold on!
type: string
required:
- code
type: object
type:
description: "`skill_card`"
enum:
- skill_card
example: skill_card
type: string
required:
- type
- skill_card_type
- skill
- invocation
- status
title: Status Skill Card
type: object
x-box-resource-id: status_skill_card
x-box-tag: skills
StoragePolicies:
allOf:
- description: |-
The part of an API response that describes marker
based pagination
properties:
limit:
description: |-
The limit that was used for these entries. This will be the same as the
`limit` query parameter unless that value exceeded the maximum value
allowed. The maximum value varies by API.
example: 1000
format: int64
type: integer
next_marker:
description: The marker for the start of the next page of results.
example: 3000
format: int64
type: integer
prev_marker:
description: The marker for the start of the previous page of results.
example: 1000
format: int64
type: integer
type: object
- properties:
entries:
items:
$ref: "#/components/schemas/StoragePolicy"
type: array
description: A list of storage policies.
title: Storage policies
type: object
x-box-resource-id: storage_policies
x-box-tag: storage_policies
StoragePolicy:
allOf:
- $ref: "#/components/schemas/StoragePolicy--Mini"
- properties:
name:
description: A descriptive name of the region
example: Montreal / Dublin
type: string
description: The Storage Policy object describes the storage zone.
title: Storage policy
type: object
x-box-resource-id: storage_policy
x-box-variant: standard
StoragePolicy--Mini:
description: A mini description of a Storage Policy object
properties:
id:
description: The unique identifier for this storage policy
example: "11446498"
type: string
type:
description: "`storage_policy`"
enum:
- storage_policy
example: storage_policy
type: string
title: Storage policy (Mini)
type: object
x-box-resource-id: storage_policy--mini
x-box-tag: storage_policies
x-box-variant: mini
x-box-variants:
- standard
- mini
StoragePolicyAssignment:
description: The assignment of a storage policy to a user or enterprise
properties:
assigned_to:
allOf:
- description: The bare basic reference for an object
properties:
id:
description: The unique identifier for this object
example: "11446498"
type: string
type:
description: The type for this object
example: file
type: string
title: Reference
type: object
- description: The enterprise or use the policy is assigned to
storage_policy:
allOf:
- $ref: "#/components/schemas/StoragePolicy--Mini"
- description: The assigned storage policy
title: Storage policy assignment
type: object
x-box-resource-id: storage_policy_assignment
x-box-tag: storage_policy_assignments
StoragePolicyAssignments:
allOf:
- description: |-
The part of an API response that describes marker
based pagination
properties:
limit:
description: |-
The limit that was used for these entries. This will be the same as the
`limit` query parameter unless that value exceeded the maximum value
allowed. The maximum value varies by API.
example: 1000
format: int64
type: integer
next_marker:
description: The marker for the start of the next page of results.
example: 3000
format: int64
type: integer
prev_marker:
description: The marker for the start of the previous page of results.
example: 1000
format: int64
type: integer
type: object
- properties:
entries:
items:
$ref: "#/components/schemas/StoragePolicyAssignment"
type: array
description: A list of storage policy assignments.
title: Storage policy assignments
type: object
x-box-resource-id: storage_policy_assignments
x-box-tag: storage_policy_assignments
Task:
description: |-
A task allows for file-centric workflows within Box. Users can
create tasks on files and assign them to other users for them to complete the
tasks.
properties:
action:
description: |-
The type of task the task assignee will be prompted to
perform.
enum:
- review
- complete
example: review
type: string
completion_rule:
description: |-
Defines which assignees need to complete this task before the task
is considered completed.
* `all_assignees` requires all assignees to review or
approve the the task in order for it to be considered completed.
* `any_assignee` accepts any one assignee to review or
approve the the task in order for it to be considered completed.
enum:
- all_assignees
- any_assignee
example: all_assignees
type: string
created_at:
description: When the task object was created
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
created_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who created the task
due_at:
description: When the task is due
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
id:
description: The unique identifier for this task
example: "11446498"
type: string
is_completed:
description: Whether the task has been completed
example: true
type: boolean
item:
allOf:
- $ref: "#/components/schemas/File--Mini"
- description: The file associated with the task
message:
description: A message that will be included with the task
example: Legal review
type: string
task_assignment_collection:
allOf:
- $ref: "#/components/schemas/TaskAssignments"
- description: |-
A collection of task assignment objects
associated with the task
type:
description: "`task`"
enum:
- task
example: task
type: string
title: Task
type: object
x-box-resource-id: task
x-box-tag: tasks
TaskAssignment:
description: A task assignment defines which task is assigned to which user to complete.
properties:
assigned_at:
description: The date at which this task was assigned to the user.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
assigned_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who assigned this task.
assigned_to:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user that the task has been assigned to.
completed_at:
description: |-
The date at which this task assignment was
completed. This will be `null` if the task is not completed yet.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
id:
description: The unique identifier for this task assignment
example: "11446498"
type: string
item:
allOf:
- $ref: "#/components/schemas/File--Mini"
- description: The file that the task has been assigned to.
message:
description: |-
A message that will is included with the task
assignment. This is visible to the assigned user in the web and mobile
UI.
example: Please review
type: string
reminded_at:
description: |-
The date at which the assigned user was reminded of this task
assignment.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
resolution_state:
description: |-
The current state of the assignment. The available states depend on
the `action` value of the task object.
enum:
- completed
- incomplete
- approved
- rejected
example: incomplete
type: string
type:
description: "`task_assignment`"
enum:
- task_assignment
example: task_assignment
type: string
title: Task assignment
type: object
x-box-resource-id: task_assignment
x-box-tag: task_assignments
TaskAssignments:
description: A list of task assignments
properties:
entries:
items:
$ref: "#/components/schemas/TaskAssignment"
type: array
total_count:
description: The total number of items in this collection.
example: 100
format: int64
type: integer
title: Task assignments
type: object
x-box-resource-id: task_assignments
x-box-tag: task_assignments
Tasks:
description: A list of tasks
properties:
entries:
items:
$ref: "#/components/schemas/Task"
type: array
total_count:
description: |-
One greater than the offset of the last entry in the entire collection.
The total number of entries in the collection may be less than
`total_count`.
example: 5000
format: int64
type: integer
title: Tasks
type: object
x-box-resource-id: tasks
x-box-tag: tasks
TermsOfService:
allOf:
- $ref: "#/components/schemas/TermsOfService--Base"
- properties:
created_at:
description: When the legal item was created
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
enterprise:
allOf:
- description: A representation of a Box enterprise
properties:
id:
description: The unique identifier for this enterprise.
example: "11446498"
type: string
name:
description: The name of the enterprise
example: Acme Inc.
type: string
type:
description: "`enterprise`"
enum:
- enterprise
example: enterprise
type: string
title: Enterprise
type: object
- description: The enterprise these terms apply to
modified_at:
description: When the legal item was modified.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
status:
description: Whether these terms are enabled or not
enum:
- enabled
- disabled
example: enabled
type: string
text:
description: |-
The text for your terms and conditions. This text could be
empty if the `status` is set to `disabled`.
example: By using this service, you agree to ...
type: string
tos_type:
description: Whether to apply these terms to managed users or external users
enum:
- managed
- external
example: managed
type: string
description: |-
The root-level record that is supposed to represent a
single Terms of Service.
title: Terms of service
type: object
x-box-resource-id: terms_of_service
x-box-variant: standard
TermsOfService--Base:
description: |-
The root-level record that is supposed to represent a
single Terms of Service.
properties:
id:
description: The unique identifier for this terms of service.
example: "11446498"
type: string
type:
description: "`terms_of_service`"
enum:
- terms_of_service
example: terms_of_service
type: string
title: Terms of service (Base)
type: object
x-box-resource-id: terms_of_service--base
x-box-tag: terms_of_services
x-box-variant: base
x-box-variants:
- base
- standard
TermsOfServiceUserStatus:
description: The association between a Terms of Service and a user
properties:
created_at:
description: When the legal item was created
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
id:
description: The unique identifier for this terms of service user status
example: "11446498"
type: string
is_accepted:
description: If the user has accepted the terms of services
example: true
type: boolean
modified_at:
description: When the legal item was modified.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
tos:
allOf:
- $ref: "#/components/schemas/TermsOfService--Base"
- description: The terms of service
type:
description: "`terms_of_service_user_status`"
enum:
- terms_of_service_user_status
example: terms_of_service_user_status
type: string
user:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user
title: Terms of service user status
type: object
x-box-resource-id: terms_of_service_user_status
x-box-tag: terms_of_service_user_statuses
TermsOfServiceUserStatuses:
description: A list of terms of service user statuses
properties:
entries:
items:
$ref: "#/components/schemas/TermsOfServiceUserStatus"
type: array
total_count:
description: The total number of objects.
example: 2
format: int64
type: integer
title: Terms of service user statuses
type: object
x-box-resource-id: terms_of_services_user_statuses
x-box-tag: terms_of_service_user_statuses
TermsOfServices:
description: A list of terms of services
properties:
entries:
items:
$ref: "#/components/schemas/TermsOfService"
type: array
total_count:
description: The total number of objects.
example: 2
format: int64
type: integer
title: Terms of services
type: object
x-box-resource-id: terms_of_services
x-box-tag: terms_of_services
TimelineSkillCard:
description: |-
A Box Skill metadata card that places a list of images on a
timeline.
properties:
created_at:
description: The optional date and time this card was created at.
example: 2018-04-13T13:53:23-07:00
format: date-time
type: string
duration:
description: An total duration in seconds of the timeline.
example: 1000
type: integer
entries:
description: A list of entries on the timeline.
items:
description: An single item that's placed on multiple items on the timeline.
properties:
appears:
description: |-
Defines a list of timestamps for when this item should appear on the
timeline.
items:
description: The timestamp for an entry.
properties:
end:
description: |-
The time in seconds when an
entry should stop appearing on a timeline.
example: 20
type: integer
start:
description: |-
The time in seconds when an
entry should start appearing on a timeline.
example: 1
type: integer
type: object
required:
- start
- end
type: array
image_url:
description: |-
The image to show on a for an entry that appears
on a timeline. This image URL is required for every entry.
The image will be shown in a
list of items (for example faces), and clicking
the image will show the user where that entry
appears during the duration of this entry.
example: https://example.com/image1.jpg
type: string
text:
description: |-
The text of the entry. This would be the display
name for an item being placed on the timeline, for example the name
of the person who was detected in a video.
example: John
type: string
type: object
type: array
invocation:
description: |-
The invocation of this service, used to track
which instance of a service applied the metadata.
properties:
id:
description: |-
A custom identifier that represent the instance of
the service that applied this metadata. For example,
if your `image-recognition-service` runs on multiple
nodes, this field can be used to identify the ID of
the node that was used to apply the metadata.
example: image-recognition-service-123
type: string
type:
description: "`skill_invocation`"
enum:
- skill_invocation
example: skill_invocation
type: string
required:
- type
- id
type: object
skill:
description: The service that applied this metadata.
properties:
id:
description: |-
A custom identifier that represent the service that
applied this metadata.
example: image-recognition-service
type: string
type:
description: "`service`"
enum:
- service
example: service
type: string
required:
- type
- id
type: object
skill_card_title:
description: The title of the card.
properties:
code:
description: An optional identifier for the title.
example: Faces
type: string
message:
description: The actual title to show in the UI.
example: Faces
type: string
required:
- message
type: object
skill_card_type:
description: "`timeline`"
enum:
- timeline
example: timeline
type: string
type:
description: "`skill_card`"
enum:
- skill_card
example: skill_card
type: string
required:
- type
- skill_card_type
- skill
- invocation
- entries
title: Timeline Skill Card
type: object
x-box-resource-id: timeline_skill_card
x-box-tag: skills
TrackingCode:
description: |-
Tracking codes allow an admin to generate reports from the admin console
and assign an attribute to a specific group of users.
This setting must be enabled for an enterprise before it can be used.
properties:
name:
description: |-
The name of the tracking code, which must be preconfigured in
the Admin Console
example: department
type: string
type:
description: "`tracking_code`"
enum:
- tracking_code
example: tracking_code
type: string
value:
description: The value of the tracking code
example: Sales
type: string
title: Tracking code
type: object
TranscriptSkillCard:
description: A Box Skill metadata card that adds a transcript to a file.
properties:
created_at:
description: The optional date and time this card was created at.
example: 2018-04-13T13:53:23-07:00
format: date-time
type: string
duration:
description: |-
An optional total duration in seconds.
Used with a `skill_card_type` of `transcript` or
`timeline`.
example: 1000
type: integer
entries:
description: |-
An list of entries for the card. This represents the individual entries of
the transcription.
items:
description: An entry in the `entries` attribute of a metadata card
properties:
appears:
description: |-
Defines when a transcribed bit of text appears. This only includes a
start time and no end time.
items:
description: The timestamp for an entry.
properties:
start:
description: |-
The time in seconds when an
entry should start appearing on a timeline.
example: 1
type: integer
type: object
required:
- start
type: array
text:
description: |-
The text of the entry. This would be the transcribed text assigned
to the entry on the timeline.
example: Hi, and welcome to this video...
type: string
type: object
type: array
invocation:
description: |-
The invocation of this service, used to track
which instance of a service applied the metadata.
properties:
id:
description: |-
A custom identifier that represent the instance of
the service that applied this metadata. For example,
if your `image-recognition-service` runs on multiple
nodes, this field can be used to identify the ID of
the node that was used to apply the metadata.
example: transciption-service-123
type: string
type:
description: "`skill_invocation`"
enum:
- skill_invocation
example: skill_invocation
type: string
required:
- type
- id
type: object
skill:
description: The service that applied this metadata.
properties:
id:
description: |-
A custom identifier that represent the service that
applied this metadata.
example: transciption-service
type: string
type:
description: "`service`"
enum:
- service
example: service
type: string
required:
- type
- id
type: object
skill_card_title:
description: The title of the card.
properties:
code:
description: An optional identifier for the title.
example: my_transcripts
type: string
message:
description: The actual title to show in the UI.
example: My Transcripts
type: string
required:
- message
type: object
skill_card_type:
description: "`transcript`"
enum:
- transcript
example: transcript
type: string
type:
description: "`skill_card`"
enum:
- skill_card
example: skill_card
type: string
required:
- type
- skill_card_type
- skill
- invocation
- entries
title: Transcript Skill Card
type: object
x-box-resource-id: transcript_skill_card
x-box-tag: skills
TrashFile:
description: Represents a trashed file.
properties:
content_created_at:
description: |-
The date and time at which this file was originally
created, which might be before it was uploaded to Box.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
content_modified_at:
description: |-
The date and time at which this file was last updated,
which might be before it was uploaded to Box.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
created_at:
description: The date and time when the file was created on Box.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: false
type: string
created_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who created this file
description:
description: The optional description of this file
example: Contract for Q1 renewal
maxLength: 256
nullable: false
type: string
etag:
description: |-
The HTTP `etag` of this file. This can be used within some API
endpoints in the `If-Match` and `If-None-Match` headers to only
perform changes on the file if (no) changes have happened.
example: "1"
nullable: true
type: string
file_version:
allOf:
- $ref: "#/components/schemas/FileVersion--Mini"
- description: The information about the current version of the file.
id:
description: |-
The unique identifier that represent a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "123456789"
nullable: false
type: string
item_status:
description: |-
Defines if this item has been deleted or not.
* `active` when the item has is not in the trash
* `trashed` when the item has been moved to the trash but not deleted
* `deleted` when the item has been permanently deleted.
enum:
- active
- trashed
- deleted
example: trashed
nullable: false
type: string
modified_at:
description: The date and time when the file was last updated on Box.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: false
type: string
modified_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who last modified this file
- nullable: false
name:
description: The name of the file
example: Contract.pdf
type: string
owned_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who owns this file
- nullable: false
parent:
allOf:
- $ref: "#/components/schemas/Folder--Mini"
- description: The folder that this file is located within.
- nullable: true
path_collection:
allOf:
- description: A list of parent folders for an item in the trash.
properties:
entries:
description: Array of folders for this item's path collection
items:
description: The parent folder for this item
properties:
etag:
description: This field is null for the Trash folder
example: null
nullable: true
type: string
id:
description: The unique identifier that represent a folder.
example: "123456789"
type: string
name:
description: The name of the Trash folder.
example: Trash
nullable: false
type: string
sequence_id:
description: This field is null for the Trash folder
example: null
nullable: true
type: string
type:
description: "`folder`"
enum:
- folder
example: folder
type: string
type: object
type: array
total_count:
description: The number of folders in this list.
example: 1
format: int64
nullable: false
type: integer
required:
- total_count
- entries
title: Path collection (Trash)
type: object
- description: |-
The tree of folders that this file is contained in,
starting at the root.
- nullable: false
purged_at:
description: |-
The time at which this file is expected to be purged
from the trash.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
sequence_id:
allOf:
- description: |-
A numeric identifier that represents the most recent user event
that has been applied to this item.
This can be used in combination with the `GET /events`-endpoint
to filter out user events that would have occurred before this
identifier was read.
An example would be where a Box Drive-like application
would fetch an item via the API, and then listen to incoming
user events for changes to the item. The application would
ignore any user events where the `sequence_id` in the event
is smaller than or equal to the `sequence_id` in the originally
fetched resource.
example: "3"
nullable: false
type: string
- nullable: false
sha1:
description: |-
The SHA1 hash of the file. This can be used to compare the contents
of a file on Box with a local file.
example: 85136C79CBF9FE36BB9D05D0639C70C265C18D37
format: digest
nullable: false
type: string
shared_link:
description: |-
The shared link for this file. This will
be `null` if a file has been trashed, since the link will no longer
be active.
example: null
nullable: true
type: string
size:
description: |-
The file size in bytes. Be careful parsing this integer as it can
get very large and cause an integer overflow.
example: 629644
nullable: false
type: integer
trashed_at:
description: The time at which this file was put in the trash.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
type:
description: "`file`"
enum:
- file
example: file
nullable: false
type: string
required:
- id
- type
- sequence_id
- sha1
- description
- size
- path_collection
- created_at
- modified_at
- modified_by
- owned_by
- item_status
title: Trashed File
type: object
x-box-resource-id: trash_file
x-box-tag: trashed_files
TrashFileRestored:
description: Represents a file restored from the trash.
properties:
content_created_at:
description: |-
The date and time at which this file was originally
created, which might be before it was uploaded to Box.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
content_modified_at:
description: |-
The date and time at which this file was last updated,
which might be before it was uploaded to Box.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
created_at:
description: The date and time when the file was created on Box.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: false
type: string
created_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who created this file
description:
description: The optional description of this file
example: Contract for Q1 renewal
maxLength: 256
nullable: false
type: string
etag:
description: |-
The HTTP `etag` of this file. This can be used within some API
endpoints in the `If-Match` and `If-None-Match` headers to only
perform changes on the file if (no) changes have happened.
example: "1"
nullable: true
type: string
file_version:
allOf:
- $ref: "#/components/schemas/FileVersion--Mini"
- description: The information about the current version of the file.
id:
description: |-
The unique identifier that represent a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.
example: "123456789"
nullable: false
type: string
item_status:
description: |-
Defines if this item has been deleted or not.
* `active` when the item has is not in the trash
* `trashed` when the item has been moved to the trash but not deleted
* `deleted` when the item has been permanently deleted.
enum:
- active
- trashed
- deleted
example: active
nullable: false
type: string
modified_at:
description: The date and time when the file was last updated on Box.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: false
type: string
modified_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who last modified this file
- nullable: false
name:
description: The name of the file
example: Contract.pdf
type: string
owned_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who owns this file
- nullable: false
parent:
allOf:
- $ref: "#/components/schemas/Folder--Mini"
- description: The folder that this file is located within.
- nullable: true
path_collection:
allOf:
- description: A list of parent folders for an item.
properties:
entries:
description: The parent folders for this item
items:
$ref: "#/components/schemas/Folder--Mini"
nullable: false
type: array
total_count:
description: The number of folders in this list.
example: 1
format: int64
nullable: false
type: integer
required:
- total_count
- entries
title: Path collection
type: object
- description: |-
The tree of folders that this file is contained in,
starting at the root.
- nullable: false
purged_at:
description: |-
The time at which this file is expected to be purged
from the trash - becomes `null` after restore.
example: null
nullable: true
type: string
sequence_id:
allOf:
- description: |-
A numeric identifier that represents the most recent user event
that has been applied to this item.
This can be used in combination with the `GET /events`-endpoint
to filter out user events that would have occurred before this
identifier was read.
An example would be where a Box Drive-like application
would fetch an item via the API, and then listen to incoming
user events for changes to the item. The application would
ignore any user events where the `sequence_id` in the event
is smaller than or equal to the `sequence_id` in the originally
fetched resource.
example: "3"
nullable: false
type: string
- nullable: false
sha1:
description: |-
The SHA1 hash of the file. This can be used to compare the contents
of a file on Box with a local file.
example: 85136C79CBF9FE36BB9D05D0639C70C265C18D37
format: digest
nullable: false
type: string
shared_link:
description: |-
The shared link for this file. This will
be `null` if a file had been trashed, even though the original shared
link does become active again.
example: null
nullable: true
type: string
size:
description: |-
The file size in bytes. Be careful parsing this integer as it can
get very large and cause an integer overflow.
example: 629644
nullable: false
type: integer
trashed_at:
description: |-
The time at which this file was put in the
trash - becomes `null` after restore.
example: null
nullable: true
type: string
type:
description: "`file`"
enum:
- file
example: file
nullable: false
type: string
required:
- id
- type
- sequence_id
- sha1
- description
- size
- path_collection
- created_at
- modified_at
- modified_by
- owned_by
- item_status
title: Trashed File (Restored)
type: object
x-box-resource-id: trash_file_restored
x-box-tag: trashed_files
TrashFolder:
description: Represents a trashed folder.
properties:
content_created_at:
description: |-
The date and time at which this folder was originally
created.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
content_modified_at:
description: The date and time at which this folder was last updated.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
created_at:
description: |-
The date and time when the folder was created. This value may
be `null` for some folders such as the root folder or the trash
folder.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
created_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who created this folder
- nullable: false
description:
allOf:
- description: The optional description of this folder
example: Legal contracts for the new ACME deal
maxLength: 256
nullable: false
type: string
- nullable: false
etag:
description: |-
The HTTP `etag` of this folder. This can be used within some API
endpoints in the `If-Match` and `If-None-Match` headers to only
perform changes on the folder if (no) changes have happened.
example: "1"
nullable: true
type: string
folder_upload_email:
description: |-
The folder upload email for this folder. This will
be `null` if a folder has been trashed, since the upload will no longer
work.
example: null
nullable: true
type: string
id:
description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting a folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folders/123`
the `folder_id` is `123`.
example: "123456789"
nullable: false
type: string
item_status:
description: |-
Defines if this item has been deleted or not.
* `active` when the item has is not in the trash
* `trashed` when the item has been moved to the trash but not deleted
* `deleted` when the item has been permanently deleted.
enum:
- active
- trashed
- deleted
example: trashed
nullable: false
type: string
modified_at:
description: |-
The date and time when the folder was last updated. This value may
be `null` for some folders such as the root folder or the trash
folder.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
modified_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who last modified this folder.
- nullable: false
name:
description: The name of the folder.
example: Contracts
nullable: false
type: string
owned_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who owns this folder.
- nullable: false
parent:
allOf:
- $ref: "#/components/schemas/Folder--Mini"
- description: |-
The optional folder that this folder is located within.
This value may be `null` for some folders such as the
root folder or the trash folder.
- nullable: true
path_collection:
allOf:
- description: A list of parent folders for an item in the trash.
properties:
entries:
description: Array of folders for this item's path collection
items:
description: The parent folder for this item
properties:
etag:
description: This field is null for the Trash folder
example: null
nullable: true
type: string
id:
description: The unique identifier that represent a folder.
example: "123456789"
type: string
name:
description: The name of the Trash folder.
example: Trash
nullable: false
type: string
sequence_id:
description: This field is null for the Trash folder
example: null
nullable: true
type: string
type:
description: "`folder`"
enum:
- folder
example: folder
type: string
type: object
type: array
total_count:
description: The number of folders in this list.
example: 1
format: int64
nullable: false
type: integer
required:
- total_count
- entries
title: Path collection (Trash)
type: object
- description: |-
The tree of folders that this file is contained in,
starting at the root.
- nullable: false
purged_at:
description: |-
The time at which this folder is expected to be purged
from the trash.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
sequence_id:
allOf:
- description: |-
A numeric identifier that represents the most recent user event
that has been applied to this item.
This can be used in combination with the `GET /events`-endpoint
to filter out user events that would have occurred before this
identifier was read.
An example would be where a Box Drive-like application
would fetch an item via the API, and then listen to incoming
user events for changes to the item. The application would
ignore any user events where the `sequence_id` in the event
is smaller than or equal to the `sequence_id` in the originally
fetched resource.
example: "3"
nullable: false
type: string
- nullable: false
shared_link:
description: |-
The shared link for this folder. This will
be `null` if a folder has been trashed, since the link will no longer
be active.
example: null
nullable: true
type: string
size:
description: |-
The folder size in bytes.
Be careful parsing this integer as its
value can get very large.
example: 629644
format: int64
nullable: false
type: integer
trashed_at:
description: The time at which this folder was put in the trash.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
type:
description: "`folder`"
enum:
- folder
example: folder
nullable: false
type: string
required:
- id
- type
- name
- description
- size
- path_collection
- created_by
- modified_by
- owned_by
- item_status
title: Trashed Folder
type: object
x-box-resource-id: trash_folder
x-box-tag: trashed_folders
TrashFolderRestored:
description: Represents a folder restored from the trash.
properties:
content_created_at:
description: |-
The date and time at which this folder was originally
created.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
content_modified_at:
description: The date and time at which this folder was last updated.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
created_at:
description: |-
The date and time when the folder was created. This value may
be `null` for some folders such as the root folder or the trash
folder.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
created_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who created this folder
- nullable: false
description:
allOf:
- description: The optional description of this folder
example: Legal contracts for the new ACME deal
maxLength: 256
nullable: false
type: string
- nullable: false
etag:
description: |-
The HTTP `etag` of this folder. This can be used within some API
endpoints in the `If-Match` and `If-None-Match` headers to only
perform changes on the folder if (no) changes have happened.
example: "1"
nullable: true
type: string
folder_upload_email:
description: |-
The folder upload email for this folder. This will
be `null` if a folder has been trashed, even though the original upload
email does become active again.
example: null
nullable: true
type: string
id:
description: |-
The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting a folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folders/123`
the `folder_id` is `123`.
example: "123456789"
nullable: false
type: string
item_status:
description: |-
Defines if this item has been deleted or not.
* `active` when the item has is not in the trash
* `trashed` when the item has been moved to the trash but not deleted
* `deleted` when the item has been permanently deleted.
enum:
- active
- trashed
- deleted
example: active
nullable: false
type: string
modified_at:
description: |-
The date and time when the folder was last updated. This value may
be `null` for some folders such as the root folder or the trash
folder.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
modified_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who last modified this folder.
- nullable: false
name:
description: The name of the folder.
example: Contracts
nullable: false
type: string
owned_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who owns this folder.
- nullable: false
parent:
allOf:
- $ref: "#/components/schemas/Folder--Mini"
- description: |-
The optional folder that this folder is located within.
This value may be `null` for some folders such as the
root folder or the trash folder.
- nullable: true
path_collection:
allOf:
- description: A list of parent folders for an item.
properties:
entries:
description: The parent folders for this item
items:
$ref: "#/components/schemas/Folder--Mini"
nullable: false
type: array
total_count:
description: The number of folders in this list.
example: 1
format: int64
nullable: false
type: integer
required:
- total_count
- entries
title: Path collection
type: object
- description: |-
The tree of folders that this file is contained in,
starting at the root.
- nullable: false
purged_at:
description: |-
The time at which this folder is expected to be purged
from the trash - becomes `null` after restore.
example: null
nullable: true
type: string
sequence_id:
allOf:
- description: |-
A numeric identifier that represents the most recent user event
that has been applied to this item.
This can be used in combination with the `GET /events`-endpoint
to filter out user events that would have occurred before this
identifier was read.
An example would be where a Box Drive-like application
would fetch an item via the API, and then listen to incoming
user events for changes to the item. The application would
ignore any user events where the `sequence_id` in the event
is smaller than or equal to the `sequence_id` in the originally
fetched resource.
example: "3"
nullable: false
type: string
- nullable: false
shared_link:
description: |-
The shared link for this file. This will
be `null` if a folder had been trashed, even though the original shared
link does become active again.
example: null
nullable: true
type: string
size:
description: |-
The folder size in bytes.
Be careful parsing this integer as its
value can get very large.
example: 629644
format: int64
nullable: false
type: integer
trashed_at:
description: |-
The time at which this folder was put in the
trash - becomes `null` after restore.
example: null
nullable: true
type: string
type:
description: "`folder`"
enum:
- folder
example: folder
nullable: false
type: string
title: Trashed Folder (Restored)
type: object
x-box-resource-id: trash_folder_restored
x-box-tag: trashed_folders
TrashWebLink:
description: Represents a trashed web link.
properties:
created_at:
description: When this file was created on Box’s servers.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
created_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who created this web link
description:
description: |-
The description accompanying the web link. This is
visible within the Box web application.
example: Example page
type: string
etag:
description: |-
The entity tag of this web link. Used with `If-Match`
headers.
example: "1"
type: string
id:
description: The unique identifier for this web link
example: "11446498"
type: string
item_status:
description: |-
Whether this item is deleted or not. Values include `active`,
`trashed` if the file has been moved to the trash, and `deleted` if
the file has been permanently deleted
enum:
- active
- trashed
- deleted
example: trashed
type: string
modified_at:
description: |-
When this file was last updated on the Box
servers.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
modified_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who last modified this web link
name:
description: The name of the web link
example: My Bookmark
type: string
owned_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who owns this web link
parent:
allOf:
- $ref: "#/components/schemas/Folder--Mini"
- description: The parent object the web link belongs to
path_collection:
allOf:
- description: A list of parent folders for an item in the trash.
properties:
entries:
description: Array of folders for this item's path collection
items:
description: The parent folder for this item
properties:
etag:
description: This field is null for the Trash folder
example: null
nullable: true
type: string
id:
description: The unique identifier that represent a folder.
example: "123456789"
type: string
name:
description: The name of the Trash folder.
example: Trash
nullable: false
type: string
sequence_id:
description: This field is null for the Trash folder
example: null
nullable: true
type: string
type:
description: "`folder`"
enum:
- folder
example: folder
type: string
type: object
type: array
total_count:
description: The number of folders in this list.
example: 1
format: int64
nullable: false
type: integer
required:
- total_count
- entries
title: Path collection (Trash)
type: object
- description: |-
The tree of folders that this web link is contained in,
starting at the root.
- nullable: false
purged_at:
description: When this file will be permanently deleted.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
sequence_id:
allOf:
- description: |-
A numeric identifier that represents the most recent user event
that has been applied to this item.
This can be used in combination with the `GET /events`-endpoint
to filter out user events that would have occurred before this
identifier was read.
An example would be where a Box Drive-like application
would fetch an item via the API, and then listen to incoming
user events for changes to the item. The application would
ignore any user events where the `sequence_id` in the event
is smaller than or equal to the `sequence_id` in the originally
fetched resource.
example: "3"
nullable: false
type: string
- nullable: false
shared_link:
description: |-
The shared link for this bookmark. This will
be `null` if a bookmark has been trashed, since the link will no longer
be active.
example: null
nullable: true
type: string
trashed_at:
description: When this file was last moved to the trash.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
type:
description: "`web_link`"
enum:
- web_link
example: web_link
type: string
url:
description: The URL this web link points to
example: https://www.example.com/example/1234
type: string
title: Trashed Web Link
type: object
x-box-resource-id: trash_web_link
x-box-tag: trashed_web_links
TrashWebLinkRestored:
description: Represents a web link restored from the trash.
properties:
created_at:
description: When this file was created on Box’s servers.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
created_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who created this web link
description:
description: |-
The description accompanying the web link. This is
visible within the Box web application.
example: Example page
type: string
etag:
description: |-
The entity tag of this web link. Used with `If-Match`
headers.
example: "1"
type: string
id:
description: The unique identifier for this web link
example: "11446498"
type: string
item_status:
description: |-
Whether this item is deleted or not. Values include `active`,
`trashed` if the file has been moved to the trash, and `deleted` if
the file has been permanently deleted
enum:
- active
- trashed
- deleted
example: trashed
type: string
modified_at:
description: |-
When this file was last updated on the Box
servers.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
modified_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who last modified this web link
name:
description: The name of the web link
example: My Bookmark
type: string
owned_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who owns this web link
parent:
allOf:
- $ref: "#/components/schemas/Folder--Mini"
- description: The parent object the web link belongs to
path_collection:
allOf:
- description: A list of parent folders for an item.
properties:
entries:
description: The parent folders for this item
items:
$ref: "#/components/schemas/Folder--Mini"
nullable: false
type: array
total_count:
description: The number of folders in this list.
example: 1
format: int64
nullable: false
type: integer
required:
- total_count
- entries
title: Path collection
type: object
- description: |-
The tree of folders that this web link is contained in,
starting at the root.
- nullable: false
purged_at:
description: |-
The time at which this bookmark will be permanently
deleted - becomes `null` after restore.
example: null
nullable: true
type: string
sequence_id:
allOf:
- description: |-
A numeric identifier that represents the most recent user event
that has been applied to this item.
This can be used in combination with the `GET /events`-endpoint
to filter out user events that would have occurred before this
identifier was read.
An example would be where a Box Drive-like application
would fetch an item via the API, and then listen to incoming
user events for changes to the item. The application would
ignore any user events where the `sequence_id` in the event
is smaller than or equal to the `sequence_id` in the originally
fetched resource.
example: "3"
nullable: false
type: string
- nullable: false
shared_link:
description: |-
The shared link for this bookmark. This will
be `null` if a bookmark had been trashed, even though the original shared
link does become active again.
example: null
nullable: true
type: string
trashed_at:
description: |-
The time at which this bookmark was put in the
trash - becomes `null` after restore.
example: null
nullable: true
type: string
type:
description: "`web_link`"
enum:
- web_link
example: web_link
type: string
url:
description: The URL this web link points to
example: https://www.example.com/example/1234
type: string
required:
- sequence_id
- path_collection
title: Trashed Web Link (Restored)
type: object
x-box-resource-id: trash_web_link_restored
x-box-tag: trashed_web_links
UploadPart:
allOf:
- $ref: "#/components/schemas/UploadPart--Mini"
- properties:
sha1:
description: The SHA1 hash of the chunk.
example: 134b65991ed521fcfe4724b7d814ab8ded5185dc
type: string
description: |-
The representation of an upload
session chunk.
title: Upload part
type: object
x-box-resource-id: upload_part
x-box-variant: standard
UploadPart--Mini:
description: |-
The basic representation of an upload
session chunk.
properties:
offset:
description: |-
The offset of the chunk within the file
in bytes. The lower bound of the position
of the chunk within the file.
example: 16777216
format: int64
type: integer
part_id:
description: The unique ID of the chunk.
example: 6F2D3486
type: string
size:
description: The size of the chunk in bytes.
example: 3222784
format: int64
type: integer
title: Upload part (Mini)
type: object
x-box-resource-id: upload_part--mini
x-box-tag: chunked_uploads
x-box-variant: mini
x-box-variants:
- mini
- standard
UploadParts:
allOf:
- description: The part of an API response that describes pagination
properties:
limit:
description: |-
The limit that was used for these entries. This will be the same as the
`limit` query parameter unless that value exceeded the maximum value
allowed. The maximum value varies by API.
example: 1000
format: int64
type: integer
offset:
description: |-
The 0-based offset of the first entry in this set. This will be the same
as the `offset` query parameter.
This field is only returned for calls that use offset-based pagination.
For marker-based paginated APIs, this field will be omitted.
example: 2000
format: int64
type: integer
order:
description: |-
The order by which items are returned.
This field is only returned for calls that use offset-based pagination.
For marker-based paginated APIs, this field will be omitted.
items:
description: The order in which a pagination is ordered
properties:
by:
description: The field to order by
example: type
type: string
direction:
description: The direction to order by, either ascending or descending
enum:
- ASC
- DESC
example: ASC
type: string
type: object
type: array
total_count:
description: |-
One greater than the offset of the last entry in the entire collection.
The total number of entries in the collection may be less than
`total_count`.
This field is only returned for calls that use offset-based pagination.
For marker-based paginated APIs, this field will be omitted.
example: 5000
format: int64
type: integer
type: object
- properties:
entries:
items:
$ref: "#/components/schemas/UploadPart"
type: array
description: |-
A list of uploaded chunks for an upload
session.
title: Upload parts
type: object
x-box-resource-id: upload_parts
x-box-tag: chunked_uploads
UploadSession:
description: An upload session for chunk uploading a file.
properties:
id:
description: The unique identifier for this session
example: F971964745A5CD0C001BBE4E58196BFD
type: string
num_parts_processed:
description: |-
The number of parts that have been uploaded and processed
by the server. This starts at `0`.
When committing a file files, inspecting this property can
provide insight if all parts have been uploaded correctly.
example: 455
format: int32
type: integer
part_size:
description: |-
The size in bytes that must be used for all parts of of the
upload.
Only the last part is allowed to be of a smaller size.
example: 1024
format: int64
type: integer
session_endpoints:
allOf:
- description: A list of endpoints for a chunked upload session.
properties:
abort:
description: The URL for used to abort the session.
example: https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD
type: string
commit:
description: The URL used to commit the file
example: https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/commit
type: string
list_parts:
description: The URL users to list all parts.
example: https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/parts
type: string
log_event:
description: The URL used to get the upload log from.
example: https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/log
type: string
status:
description: The URL used to get the status of the upload.
example: https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD
type: string
upload_part:
description: The URL to upload parts to
example: https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD
type: string
title: Session endpoints
type: object
- description: A list of endpoints for this session.
session_expires_at:
description: The date and time when this session expires.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
total_parts:
description: |-
The total number of parts expected in this upload session,
as determined by the file size and part size.
example: 1000
format: int32
type: integer
type:
description: "`upload_session`"
enum:
- upload_session
example: upload_session
type: string
title: Upload session
type: object
x-box-resource-id: upload_session
x-box-tag: chunked_uploads
UploadUrl:
description: The details for the upload session for the file.
properties:
upload_token:
description: An optional access token to use to upload the file
example: Pc3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQP
type: string
upload_url:
description: |-
A URL for an upload session that can be used to upload
the file.
example: https://upload-las.app.box.com/api/2.0/files/content?upload_session_id=1234
type: string
title: Upload URL
type: object
x-box-resource-id: upload_url
x-box-tag: uploads
UploadedPart:
description: |-
A chunk of a file uploaded as part of
an upload session, as returned by some endpoints.
properties:
part:
$ref: "#/components/schemas/UploadPart"
title: Uploaded part
type: object
x-box-resource-id: uploaded_part
x-box-tag: chunked_uploads
User:
allOf:
- $ref: "#/components/schemas/User--Mini"
- properties:
address:
description: The user’s address
example: 900 Jefferson Ave, Redwood City, CA 94063
maxLength: 255
type: string
avatar_url:
description: URL of the user’s avatar image
example: https://www.box.com/api/avatar/large/181216415
type: string
created_at:
description: When the user object was created
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
job_title:
description: The user’s job title
example: CEO
maxLength: 100
type: string
language:
description: |-
The language of the user, formatted in modified version of the
[ISO 639-1](/guides/api-calls/language-codes) format.
example: en
type: string
max_upload_size:
description: The maximum individual file size in bytes the user can have
example: 2147483648
format: int64
type: integer
modified_at:
description: When the user object was last modified
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
notification_email:
description: |-
An alternate notification email address to which email
notifications are sent. When it's confirmed, this will be
the email address to which notifications are sent instead of
to the primary email address.
nullable: true
properties:
email:
description: The email address to send the notifications to.
example: notifications@example.com
type: string
is_confirmed:
description: Specifies if this email address has been confirmed.
example: true
type: boolean
type: object
phone:
description: The user’s phone number
example: "6509241374"
maxLength: 100
type: string
space_amount:
description: The user’s total available space amount in bytes
example: 11345156112
format: int64
type: integer
space_used:
description: The amount of space in use by the user
example: 1237009912
format: int64
type: integer
status:
description: The user's account status
enum:
- active
- inactive
- cannot_delete_edit
- cannot_delete_edit_upload
example: active
type: string
timezone:
description: The user's timezone
example: Africa/Bujumbura
format: timezone
type: string
description: |-
A standard representation of a user, as returned from any
user API endpoints by default
title: User
type: object
x-box-resource-id: user
x-box-variant: standard
User--Base:
description: |-
A mini representation of a user, used when
nested within another resource.
properties:
id:
description: The unique identifier for this user
example: "11446498"
type: string
type:
description: "`user`"
enum:
- user
example: user
nullable: false
type: string
required:
- type
title: User (Base)
type: object
x-box-resource-id: user--base
x-box-tag: users
x-box-variant: base
x-box-variants:
- base
- mini
- standard
- full
User--Collaborations:
allOf:
- $ref: "#/components/schemas/User--Base"
- properties:
login:
description: The primary email address of this user. If the collaboration status is `pending`, an empty string is returned.
example: ceo@example.com
format: email
nullable: false
type: string
name:
description: The display name of this user. If the collaboration status is `pending`, an empty string is returned.
example: Aaron Levie
maxLength: 50
nullable: false
type: string
description: |-
A mini representation of a user, can be returned only when
the status is `pending`.
required:
- name
- login
title: User (Collaborations)
type: object
x-box-resource-id: user_collaborations
x-box-variant: collaborations
User--Full:
allOf:
- $ref: "#/components/schemas/User"
- properties:
can_see_managed_users:
description: Whether the user can see other enterprise users in their contact list
example: true
type: boolean
enterprise:
allOf:
- description: A representation of a Box enterprise
properties:
id:
description: The unique identifier for this enterprise.
example: "11446498"
type: string
name:
description: The name of the enterprise
example: Acme Inc.
type: string
type:
description: "`enterprise`"
enum:
- enterprise
example: enterprise
type: string
title: Enterprise
type: object
- description: Representation of the user’s enterprise
external_app_user_id:
description: |-
An external identifier for an app user, which can be used to look up
the user. This can be used to tie user IDs from external identity
providers to Box users.
example: my-user-1234
type: string
hostname:
description: |-
The root (protocol, subdomain, domain) of any links that need to be
generated for the user
example: https://example.app.box.com/
type: string
is_exempt_from_device_limits:
description: Whether to exempt the user from Enterprise device limits
example: true
type: boolean
is_exempt_from_login_verification:
description: Whether the user must use two-factor authentication
example: true
type: boolean
is_external_collab_restricted:
description: |-
Whether the user is allowed to collaborate with users outside their
enterprise
example: true
type: boolean
is_platform_access_only:
description: Whether the user is an App User
example: true
type: boolean
is_sync_enabled:
description: Whether the user can use Box Sync
example: true
type: boolean
my_tags:
description: |-
Tags for all files and folders owned by the user. Values returned
will only contain tags that were set by the requester.
example:
- important
items:
type: string
type: array
role:
description: The user’s enterprise role
enum:
- admin
- coadmin
- user
example: admin
type: string
tracking_codes:
description: |-
Tracking codes allow an admin to generate reports from the
admin console and assign an attribute to a specific group
of users. This setting must be enabled for an enterprise
before it can be used.
items:
$ref: "#/components/schemas/TrackingCode"
type: array
description: |-
A full representation of a user, as can be returned from any
user API endpoint.
title: User (Full)
type: object
x-box-resource-id: user--full
x-box-variant: full
User--Mini:
allOf:
- $ref: "#/components/schemas/User--Base"
- properties:
login:
description: The primary email address of this user
example: ceo@example.com
format: email
nullable: false
type: string
name:
description: The display name of this user
example: Aaron Levie
maxLength: 50
nullable: false
type: string
description: |-
A mini representation of a user, as can be returned when nested within other
resources.
required:
- name
- login
title: User (Mini)
type: object
x-box-resource-id: user--mini
x-box-variant: mini
UserAvatar:
description: |-
A resource holding URLs to the
avatar uploaded to a Box application.
properties:
pic_urls:
description: Represents an object with user avatar URLs.
properties:
large:
description: The location of a large-sized avatar.
example: https://app.box.com/index.php?rm=pic_storage_auth&pic=euks pac3kv01!lipGQlQQOtCTCoB6zCOArUjVWLFJtLr5tn6aOZMCybhRx0NNuFQbVI36nw jtEk5YjUUz1KVdVuvU2yDhu_ftK_bvxeKP1Ffrx9vKGVvJ-UJc1z32p6n2CmFzzpc gSoX4pnPhFgydAL-u9jDspXUGElr-htDG_HPMiE9DZjqDueOxXHy8xe22wbaPAheC ao1emv8r_fmufaUgSndeMYmyZj-KqOYsLBrBNgdeiK5tZmPOQggAEUmyQPkrd8W92TQ6sSlIp0r
type: string
preview:
description: The location of the avatar preview.
example: https://app.box.com/index.php?rm=pic_storage_auth&pic=euks! pac3kv01!8UcNPweOOAWj2DtHk_dCQB4wJpzyPkl7mT5nHj5ZdjY92ejYCBBZc95--403b29CW k-8hSo_uBjh5h9QG42Ihu-cOZ-816sej1kof3SOm5gjn7qjMAx89cHjUaNK-6XasRqSNboenjZ 04laZuV9vSH12BZGAYycIZvvQ5R66Go8xG5GTMARf2nBU84c4H_SL5iws-HeBS4oQJWOJh6FBl sSJDSTI74LGXqeZb3EY_As34VFC95F10uozoTOSubZmPYylPlaKXoKWk2f9wYQso1ZTN7sh-Gc 9Kp43zMLhArIWhok0Im6FlRAuWOQ03KYgL-k4L5EZp4Gw6B7uqVRwcBbsTwMIorWq1g
type: string
small:
description: The location of a small-sized avatar.
example: https://app.box.com/index.php?rm=pic_storage_auth&pic=euks! pac3kv01!7B6R5cZLmurEV_xB-KkycPk8Oi7oENUX2O_qUtIuO4342CG IldyCto9hqiQP7uxqYU5V2w63Ft4ln4UVVLDtDZu903OqzkflY2O-Lq00 ubA29xU-RJ6b_KzJEWRYgUhX1zEl3dzWo12g8eWRE2rStf123DF7AYahNqM 1BmLmviL_nODc7SDQHedTXPAjxURUAra5BvtLe7B05AizbNXdPlCNp-LNh _S-eZ_RjDXcGO-MkRWd_3BOMHnvjf450t5BfKoJ15WhEfiMlfXH1tmouHXrsC 66cT6-pzF9E40Iir_zThqSlrFxzP_xcmXzHapr_k-0E2qr2TXp4iC396TSlEw
type: string
type: object
title: User avatar
type: object
x-box-resource-id: user_avatar
x-box-tag: avatars
Users:
allOf:
- description: The part of an API response that describes pagination
properties:
limit:
description: |-
The limit that was used for these entries. This will be the same as the
`limit` query parameter unless that value exceeded the maximum value
allowed. The maximum value varies by API.
example: 1000
format: int64
type: integer
offset:
description: |-
The 0-based offset of the first entry in this set. This will be the same
as the `offset` query parameter.
This field is only returned for calls that use offset-based pagination.
For marker-based paginated APIs, this field will be omitted.
example: 2000
format: int64
type: integer
order:
description: |-
The order by which items are returned.
This field is only returned for calls that use offset-based pagination.
For marker-based paginated APIs, this field will be omitted.
items:
description: The order in which a pagination is ordered
properties:
by:
description: The field to order by
example: type
type: string
direction:
description: The direction to order by, either ascending or descending
enum:
- ASC
- DESC
example: ASC
type: string
type: object
type: array
total_count:
description: |-
One greater than the offset of the last entry in the entire collection.
The total number of entries in the collection may be less than
`total_count`.
This field is only returned for calls that use offset-based pagination.
For marker-based paginated APIs, this field will be omitted.
example: 5000
format: int64
type: integer
type: object
- properties:
entries:
items:
$ref: "#/components/schemas/User"
type: array
description: A list of users.
title: Users
type: object
x-box-resource-id: users
x-box-tag: users
Watermark:
description: |-
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 a file's content
properties:
watermark:
properties:
created_at:
description: When this watermark was created
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
modified_at:
description: When this task was modified
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
type: object
title: Watermark
type: object
x-box-resource-id: watermark
x-box-tag: file_watermarks
WebLink:
allOf:
- $ref: "#/components/schemas/WebLink--Mini"
- properties:
created_at:
description: When this file was created on Box’s servers.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
created_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who created this web link
description:
description: |-
The description accompanying the web link. This is
visible within the Box web application.
example: Example page
type: string
item_status:
description: |-
Whether this item is deleted or not. Values include `active`,
`trashed` if the file has been moved to the trash, and `deleted` if
the file has been permanently deleted
enum:
- active
- trashed
- deleted
example: active
type: string
modified_at:
description: |-
When this file was last updated on the Box
servers.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
modified_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who last modified this web link
owned_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who owns this web link
parent:
allOf:
- $ref: "#/components/schemas/Folder--Mini"
- description: The parent object the web link belongs to
path_collection:
allOf:
- description: A list of parent folders for an item.
properties:
entries:
description: The parent folders for this item
items:
$ref: "#/components/schemas/Folder--Mini"
nullable: false
type: array
total_count:
description: The number of folders in this list.
example: 1
format: int64
nullable: false
type: integer
required:
- total_count
- entries
title: Path collection
type: object
- description: |-
The tree of folders that this web link is contained in,
starting at the root.
- nullable: false
purged_at:
description: When this file will be permanently deleted.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
shared_link:
allOf:
- description: |-
Shared links provide direct, read-only access to files or folder on Box.
Shared links with open access level allow anyone with the URL
to access the item, while shared links with company or collaborators access
levels can only be accessed by appropriately authenticated Box users.
properties:
access:
description: |-
The access level for this shared link.
* `open` - provides access to this item to anyone with this link
* `company` - only provides access to this item to people the same company
* `collaborators` - only provides access to this item to people who are
collaborators on this item
If this field is omitted when creating the shared link, the access level
will be set to the default access level specified by the enterprise admin.
enum:
- open
- company
- collaborators
example: open
nullable: false
type: string
download_count:
description: The number of times this item has been downloaded.
example: 3
nullable: false
type: integer
download_url:
description: |-
A URL that can be used to download the file. This URL can be used in
a browser to download the file. This URL includes the file
extension so that the file will be saved with the right file type.
This property will be `null` for folders.
example: https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg
format: url
nullable: true
type: string
x-box-premium-feature: true
effective_access:
description: |-
The effective access level for the shared link. This can be a more
restrictive access level than the value in the `access` field when the
enterprise settings restrict the allowed access levels.
enum:
- open
- company
- collaborators
example: company
nullable: false
type: string
effective_permission:
description: |-
The effective permissions for this shared link.
These result in the more restrictive combination of
the share link permissions and the item permissions set
by the administrator, the owner, and any ancestor item
such as a folder.
enum:
- can_edit
- can_download
- can_preview
- no_access
example: can_download
nullable: false
type: string
is_password_enabled:
description: Defines if the shared link requires a password to access the item.
example: true
nullable: false
type: boolean
permissions:
description: |-
Defines if this link allows a user to preview, edit, and download an item.
These permissions refer to the shared link only and
do not supersede permissions applied to the item itself.
properties:
can_download:
description: |-
Defines if the shared link allows for the item to be downloaded. For
shared links on folders, this also applies to any items in the folder.
This value can be set to `true` when the effective access level is
set to `open` or `company`, not `collaborators`.
example: true
nullable: false
type: boolean
can_edit:
description: |-
Defines if the shared link allows for the item to be edited.
This value can only be `true` if `can_download` is also `true` and if
the item has a type of `file`.
example: false
nullable: false
type: boolean
can_preview:
description: |-
Defines if the shared link allows for the item to be previewed.
This value is always `true`. For shared links on folders this also
applies to any items in the folder.
example: true
nullable: false
type: boolean
required:
- can_download
- can_preview
- can_edit
type: object
preview_count:
description: The number of times this item has been previewed.
example: 3
nullable: false
type: integer
unshared_at:
description: |-
The date and time when this link will be unshared. This field can only be
set by users with paid accounts.
example: 2018-04-13T13:53:23-07:00
format: date-time
nullable: true
type: string
url:
description: |-
The URL that can be used to access the item on Box.
This URL will display the item in Box's preview UI where the file
can be downloaded if allowed.
This URL will continue to work even when a custom `vanity_url`
has been set for this shared link.
example: https://www.box.com/s/vspke7y05sb214wjokpk
format: url
nullable: false
type: string
vanity_name:
description: The custom name of a shared link, as used in the `vanity_url` field.
example: my_url
nullable: true
type: string
vanity_url:
description: |-
The "Custom URL" that can also be used to preview the item on Box. Custom
URLs can only be created or modified in the Box Web application.
example: https://acme.app.box.com/v/my_url/
format: url
nullable: true
type: string
required:
- url
- accessed
- effective_access
- effective_permission
- is_password_enabled
- download_count
- preview_count
title: Shared link
type: object
- description: |-
The shared link object for this item. Will be
`null` if no shared link has been created.
- nullable: true
trashed_at:
description: When this file was moved to the trash.
example: 2012-12-12T10:53:43-08:00
format: date-time
nullable: true
type: string
description: |-
Web links are objects that point to URLs. These objects
are also known as bookmarks within the Box web application.
Web link objects are treated similarly to file objects,
they will also support most actions that apply to regular files.
title: Web link
type: object
x-box-resource-id: web_link
x-box-variant: standard
WebLink--Base:
description: |-
Web links are objects that point to URLs. These objects
are also known as bookmarks within the Box web application.
Web link objects are treated similarly to file objects,
they will also support most actions that apply to regular files.
properties:
etag:
description: |-
The entity tag of this web link. Used with `If-Match`
headers.
example: "1"
type: string
id:
description: The unique identifier for this web link
example: "11446498"
type: string
type:
description: "`web_link`"
enum:
- web_link
example: web_link
type: string
required:
- id
- type
title: Web link (Base)
type: object
x-box-resource-id: web_link--base
x-box-tag: web_links
x-box-variant: base
x-box-variants:
- base
- mini
- standard
WebLink--Mini:
allOf:
- $ref: "#/components/schemas/WebLink--Base"
- properties:
name:
description: The name of the web link
example: My Bookmark
type: string
sequence_id:
allOf:
- description: |-
A numeric identifier that represents the most recent user event
that has been applied to this item.
This can be used in combination with the `GET /events`-endpoint
to filter out user events that would have occurred before this
identifier was read.
An example would be where a Box Drive-like application
would fetch an item via the API, and then listen to incoming
user events for changes to the item. The application would
ignore any user events where the `sequence_id` in the event
is smaller than or equal to the `sequence_id` in the originally
fetched resource.
example: "3"
nullable: false
type: string
- nullable: false
url:
description: The URL this web link points to
example: https://www.example.com/example/1234
type: string
description: |-
Web links are objects that point to URLs. These objects
are also known as bookmarks within the Box web application.
Web link objects are treated similarly to file objects,
they will also support most actions that apply to regular files.
title: Web link (Mini)
type: object
x-box-resource-id: web_link--mini
x-box-variant: mini
Webhook:
allOf:
- $ref: "#/components/schemas/Webhook--Mini"
- properties:
address:
description: The URL that is notified by this webhook
example: https://example.com/webhooks
type: string
created_at:
description: |-
A timestamp identifying the time that
the webhook was created.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
created_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user who created the webhook
triggers:
description: |-
An array of event names that this webhook is
to be triggered for
example:
- FILE.UPLOADED
items:
description: The event name that triggered this webhook
enum:
- FILE.UPLOADED
- FILE.PREVIEWED
- FILE.DOWNLOADED
- FILE.TRASHED
- FILE.DELETED
- FILE.RESTORED
- FILE.COPIED
- FILE.MOVED
- FILE.LOCKED
- FILE.UNLOCKED
- FILE.RENAMED
- COMMENT.CREATED
- COMMENT.UPDATED
- COMMENT.DELETED
- TASK_ASSIGNMENT.CREATED
- TASK_ASSIGNMENT.UPDATED
- METADATA_INSTANCE.CREATED
- METADATA_INSTANCE.UPDATED
- METADATA_INSTANCE.DELETED
- FOLDER.CREATED
- FOLDER.RENAMED
- FOLDER.DOWNLOADED
- FOLDER.RESTORED
- FOLDER.DELETED
- FOLDER.COPIED
- FOLDER.MOVED
- FOLDER.TRASHED
- WEBHOOK.DELETED
- COLLABORATION.CREATED
- COLLABORATION.ACCEPTED
- COLLABORATION.REJECTED
- COLLABORATION.REMOVED
- COLLABORATION.UPDATED
- SHARED_LINK.DELETED
- SHARED_LINK.CREATED
- SHARED_LINK.UPDATED
- SIGN_REQUEST.COMPLETED
- SIGN_REQUEST.DECLINED
- SIGN_REQUEST.EXPIRED
example: FILE.UPLOADED
title: Webhook Trigger
type: string
type: array
description: Represents a configured webhook.
title: Webhook
type: object
x-box-resource-id: webhook
x-box-tag: webhooks
x-box-variant: standard
Webhook--Mini:
description: Represents a configured webhook.
properties:
id:
description: The unique identifier for this webhook.
example: "11446498"
type: string
target:
description: The item that will trigger the webhook
properties:
id:
description: The ID of the item to trigger a webhook
example: "1231232"
type: string
type:
description: The type of item to trigger a webhook
enum:
- file
- folder
example: file
type: string
type: object
type:
description: "`webhook`"
enum:
- webhook
example: webhook
type: string
title: Webhook (Mini)
type: object
x-box-resource-id: webhook--mini
x-box-tag: webhooks
x-box-variant: mini
x-box-variants:
- mini
- standard
WebhookInvocation:
description: The event that is sent to a webhook address when an event happens.
properties:
created_at:
description: |-
A timestamp identifying the time that
the webhook event was triggered.
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
created_by:
allOf:
- $ref: "#/components/schemas/User--Mini"
- description: The user that triggered this event
id:
description: The unique identifier for this webhook invocation
example: "11446498"
type: string
source:
allOf:
- oneOf:
- $ref: "#/components/schemas/File"
- $ref: "#/components/schemas/Folder"
- description: The item that caused the event to trigger
trigger:
allOf:
- description: The event name that triggered this webhook
enum:
- FILE.UPLOADED
- FILE.PREVIEWED
- FILE.DOWNLOADED
- FILE.TRASHED
- FILE.DELETED
- FILE.RESTORED
- FILE.COPIED
- FILE.MOVED
- FILE.LOCKED
- FILE.UNLOCKED
- FILE.RENAMED
- COMMENT.CREATED
- COMMENT.UPDATED
- COMMENT.DELETED
- TASK_ASSIGNMENT.CREATED
- TASK_ASSIGNMENT.UPDATED
- METADATA_INSTANCE.CREATED
- METADATA_INSTANCE.UPDATED
- METADATA_INSTANCE.DELETED
- FOLDER.CREATED
- FOLDER.RENAMED
- FOLDER.DOWNLOADED
- FOLDER.RESTORED
- FOLDER.DELETED
- FOLDER.COPIED
- FOLDER.MOVED
- FOLDER.TRASHED
- WEBHOOK.DELETED
- COLLABORATION.CREATED
- COLLABORATION.ACCEPTED
- COLLABORATION.REJECTED
- COLLABORATION.REMOVED
- COLLABORATION.UPDATED
- SHARED_LINK.DELETED
- SHARED_LINK.CREATED
- SHARED_LINK.UPDATED
- SIGN_REQUEST.COMPLETED
- SIGN_REQUEST.DECLINED
- SIGN_REQUEST.EXPIRED
example: FILE.UPLOADED
title: Webhook Trigger
type: string
- description: The event name that triggered this webhook
type:
description: "`webhook_event`"
enum:
- webhook_event
example: webhook_event
type: string
webhook:
allOf:
- $ref: "#/components/schemas/Webhook"
- description: The webhook object that triggered this event
title: Webhook (V2) payload
type: object
x-box-resource-id: webhook_invocation
x-box-tag: webhooks
Webhooks:
allOf:
- description: |-
The part of an API response that describes marker
based pagination
properties:
limit:
description: |-
The limit that was used for these entries. This will be the same as the
`limit` query parameter unless that value exceeded the maximum value
allowed. The maximum value varies by API.
example: 1000
format: int64
type: integer
next_marker:
description: The marker for the start of the next page of results.
example: 3000
format: int64
type: integer
prev_marker:
description: The marker for the start of the previous page of results.
example: 1000
format: int64
type: integer
type: object
- properties:
entries:
items:
$ref: "#/components/schemas/Webhook--Mini"
type: array
description: A list of webhooks.
title: Webhooks
type: object
x-box-resource-id: webhooks
x-box-tag: webhooks
Workflow:
allOf:
- $ref: "#/components/schemas/Workflow--Mini"
- properties:
flows:
description: A list of flows assigned to a workflow.
items:
description: |-
A step in a Box Relay Workflow. Each flow contains a `Trigger` and
a collection of Outcomes to perform once the conditions of a
`Trigger` are met
properties:
created_at:
description: When this flow was created
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
created_by:
allOf:
- $ref: "#/components/schemas/User--Base"
- description: The user who created this flow
id:
description: The identifier of the flow
example: "12345"
type: string
outcomes:
allOf:
- items:
description: List of outcomes to perform once the conditions of trigger are met.
properties:
action_type:
allOf:
- description: The type of outcome
enum:
- add_metadata
- assign_task
- copy_file
- copy_folder
- create_folder
- delete_file
- delete_folder
- lock_file
- move_file
- move_folder
- remove_watermark_file
- rename_folder
- restore_folder
- share_file
- share_folder
- unlock_file
- upload_file
- wait_for_task
- watermark_file
- go_back_to_step
- apply_file_classification
- apply_folder_classification
- send_notification
example: assign_task
title: Action Type
type: string
- description: The type of outcome
id:
description: The identifier of the outcome
example: "12345"
type: string
if_rejected:
description: |-
If `action_type` is `assign_task` and the task is rejected, returns a
list of outcomes to complete
items:
properties:
action_type:
allOf:
- description: The type of outcome
enum:
- add_metadata
- assign_task
- copy_file
- copy_folder
- create_folder
- delete_file
- delete_folder
- lock_file
- move_file
- move_folder
- remove_watermark_file
- rename_folder
- restore_folder
- share_file
- share_folder
- unlock_file
- upload_file
- wait_for_task
- watermark_file
- go_back_to_step
- apply_file_classification
- apply_folder_classification
- send_notification
example: assign_task
title: Action Type
type: string
- description: The type of outcome
id:
description: The identifier of the outcome
example: "12345"
type: string
name:
description: The name of the outcome
example: Approval Rejection Outcome
type: string
type:
description: The outcomes resource type
enum:
- outcome
example: outcome
type: string
type: object
type: array
name:
description: The name of the outcome
example: Task Approval Outcome
type: string
type:
description: The outcomes resource type
enum:
- outcome
example: outcome
type: string
type: object
type: array
- description: Actions that are completed once the flow is triggered
trigger:
allOf:
- properties:
scope:
description: List of trigger scopes
items:
description: Object that describes where and how a Trigger condition is met
properties:
object:
description: The object the `ref` points to
properties:
id:
description: The id of the object
example: "12345"
type: string
type:
description: The type of the object
enum:
- folder
example: folder
type: string
type: object
ref:
description: Indicates the path of the condition value to check
example: /event/source/parameters/folder
type: string
type:
description: The trigger scope's resource type
enum:
- trigger_scope
example: trigger_scope
type: string
type: object
type: array
trigger_type:
description: The type of trigger selected for this flow
enum:
- WORKFLOW_MANUAL_START
example: WORKFLOW_MANUAL_START
type: string
type:
description: The trigger's resource type
enum:
- trigger
example: trigger
type: string
type: object
- description: Trigger that initiates flow
type:
description: The flow's resource type
enum:
- flow
example: flow
type: string
type: object
type: array
description: |-
Box Relay Workflows are objects that represent a named collection of flows.
Your application must be authorized to use the `Manage Box Relay` application
scope within the developer console in order to use this resource.
title: Workflow
type: object
x-box-resource-id: workflow
x-box-variant: standard
Workflow--Full:
allOf:
- $ref: "#/components/schemas/Workflow"
- properties:
created_at:
description: The date and time when the workflow was created on Box
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
created_by:
allOf:
- $ref: "#/components/schemas/User--Base"
- description: The user who created this workflow
modified_at:
description: The date and time when the workflow was last updated on Box
example: 2012-12-12T10:53:43-08:00
format: date-time
type: string
modified_by:
allOf:
- $ref: "#/components/schemas/User--Base"
- description: The user who last modified this workflow
description: |-
Box Relay Workflows are objects that represent a named collection of flows.
You application must be authorized to use the `Manage Box Relay` application
scope within the developer console in order to use this resource.
title: Workflow (Full)
type: object
x-box-resource-id: workflow--full
x-box-variant: full
Workflow--Mini:
description: |-
Box Relay Workflows are objects that represent a named collection of flows.
You application must be authorized to use the `Manage Box Relay` application
scope within the developer console in order to use this resource.
properties:
description:
description: The description for a workflow.
example: This workflow sets off a new hire approval flow
type: string
id:
description: The unique identifier for the workflow
example: "11446498"
type: string
is_enabled:
description: Specifies if this workflow is enabled
example: true
type: boolean
name:
description: The name of the workflow
example: New Hire Workflow
type: string
type:
description: "`workflow`"
enum:
- workflow
example: workflow
type: string
title: Workflow (Mini)
type: object
x-box-resource-id: workflow--mini
x-box-tag: workflows
x-box-variant: mini
x-box-variants:
- mini
- standard
- full
Workflows:
allOf:
- description: |-
The part of an API response that describes marker
based pagination
properties:
limit:
description: |-
The limit that was used for these entries. This will be the same as the
`limit` query parameter unless that value exceeded the maximum value
allowed. The maximum value varies by API.
example: 1000
format: int64
type: integer
next_marker:
description: The marker for the start of the next page of results.
example: 3000
format: int64
type: integer
prev_marker:
description: The marker for the start of the previous page of results.
example: 1000
format: int64
type: integer
type: object
- properties:
entries:
items:
$ref: "#/components/schemas/Workflow"
type: array
description: |-
A list of workflows.
You application must be authorized to use the `Manage Box Relay` application
scope within the developer console in order to use this resource.
title: Workflows
type: object
x-box-resource-id: workflows
x-box-tag: workflows
ZipDownload:
description: |-
Represents a successful request to create a `zip` archive of a list of files
and folders.
example:
download_url: https://dl.boxcloud.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/content
expires_at: 2020-07-22T11:26:08Z
name_conflicts:
- - download_name: 3aa6a7.pdf
id: "12345"
original_name: Report.pdf
type: file
- download_name: 5d53f2.pdf
id: "34325"
original_name: Report.pdf
type: file
status_url: https://api.box.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/status
properties:
download_url:
description: |-
The URL that can be used to download the `zip` archive. A `Get` request to
this URL will start streaming the items requested. By default, this URL
is only valid for a few seconds, until the `expires_at` time, unless a
download is started after which it is valid for the duration of the
download.
It is important to note that the domain and path of this URL might change
between API calls, and therefore it's important to use this URL as-is.
example: https://dl.boxcloud.com/2.0/zip_downloads/Lu6fA9Ob-jyysp3AAvMF4AkLEwZwAYbL=tgj2zIC=eK9RvJnJbjJl9rNh2qBgHDpyOCAOhpM=vajg2mKq8Mdd/content
type: string
expires_at:
description: |-
The time and date when this archive will expire. After this time the
`status_url` and `download_url` will return an error.
By default, these URLs are only valid for a few seconds, unless a download
is started after which the `download_url` is valid for the duration of the
download, and the `status_url` is valid for 12 hours from the start of the
download.
example: 2019-08-29T23:59:00-07:00
format: date-time
type: string
name_conflicts:
description: |-
A list of conflicts that occurred when trying to create the archive. This
would occur when multiple items have been requested with the
same name.
To solve these conflicts, the API will automatically rename an item
and return a mapping between the original item's name and its new
name.
For every conflict, both files will be renamed and therefore this list
will always be a multiple of 2.
items:
description: |-
An individual conflict that occurred when trying to create the archive.
This includes an array of 2 objects, each containing the original name
and the renamed filename of a file or folder for which the names
conflicted.
items:
description: A file or folder for which a conflict was encountered, This object provides the type and identifier of the original item, as well as a mapping between its original name and it's new name as it will appear in the archive.
properties:
download_name:
description: |-
The new name of this item as it will appear in the
downloaded `zip` archive.
example: 3aa6a7.pdf
type: string
id:
description: The identifier of the item
example: "12345"
type: string
original_name:
description: The original name of this item
example: Report.pdf
type: string
type:
description: The type of this item
enum:
- file
- folder
example: file
type: string
type: object
type: array
type: array
status_url:
description: |-
The URL that can be used to get the status of the `zip` archive being
downloaded. A `Get` request to this URL will return the number of files
in the archive as well as the number of items already downloaded or
skipped. By default, this URL is only valid for a few seconds, until the
`expires_at` time, unless a download is started after which the URL is
valid for 12 hours from the start of the download.
It is important to note that the domain and path of this URL might change
between API calls, and therefore it's important to use this URL as-is.
example: https://api.box.com/2.0/zip_downloads/Lu6fA9Ob-jyysp3AAvMF4AkLEwZwAYbL=tgj2zIC=eK9RvJnJbjJl9rNh2qBgHDpyOCAOhpM=vajg2mKq8Mdd/status
type: string
title: Zip download
type: object
x-box-reference-category: zip_downloads
x-box-resource-id: zip_download
x-box-tag: zip_downloads
ZipDownloadRequest:
description: A request to create a `zip` archive to download
properties:
download_file_name:
description: |-
The optional name of the `zip` archive. This name will be appended by the
`.zip` file extension, for example `January Financials.zip`.
example: January Financials
type: string
items:
description: |-
A list of items to add to the `zip` archive. These can
be folders or files.
items:
description: An item to add to the `zip` archive. This can be a file or a folder.
properties:
id:
description: |-
The identifier of the item to add to the archive. When this item is
a folder then this can not be the root folder with ID `0`.
example: "12345"
type: string
type:
description: The type of the item to add to the archive.
enum:
- file
- folder.
example: file
type: string
required:
- type
- id
type: object
type: array
required:
- items
title: Create a `zip` archive
type: object
ZipDownloadStatus:
description: The status of a `zip` archive being downloaded.
properties:
downloaded_file_count:
description: The number of files that have already been downloaded.
example: 10
minimum: 0
type: integer
skipped_file_count:
description: |-
The number of files that have been skipped as they could not be
downloaded. In many cases this is due to permission issues that have
surfaced between the creation of the request for the archive and the
archive being downloaded.
example: 5
minimum: 0
type: integer
skipped_folder_count:
description: |-
The number of folders that have been skipped as they could not be
downloaded. In many cases this is due to permission issues that have
surfaced between the creation of the request for the archive and the
archive being downloaded.
example: 5
minimum: 0
type: integer
state:
default: in_progress
description: The state of the archive being downloaded.
enum:
- in_progress
- failed
- success
example: success
type: string
total_file_count:
description: The total number of files in the archive.
example: 20
maximum: 10000
minimum: 0
type: integer
title: Zip download status
type: object
x-box-reference-category: zip_downloads
x-box-resource-id: zip_download_status
x-box-tag: zip_downloads
securitySchemes:
OAuth2Security:
flows:
authorizationCode:
authorizationUrl: https://account.box.com/api/oauth2/authorize
scopes:
manage_app_users: Provision and manage app users
manage_data_retention: Manage data retention polices
manage_enterprise_properties: Manage enterprise properties
manage_groups: Manage an enterprise's groups
manage_legal_hold: Manage Legal Holds
manage_managed_users: Provision and manage managed users
manage_webhook: Create webhooks programmatically through the API
root_readonly: Read all files and folders stored in Box
root_readwrite: Read and write all files and folders stored in Box
tokenUrl: https://api.box.com/oauth2/token
type: oauth2