Box Folder Locks API
The Box Folder Locks API provides endpoints for creating, listing, and deleting folder locks, which prevent folders from being moved or deleted by users other than the lock creator.
OpenAPI Specification
openapi: 3.1.0
info:
title: Box Folder Locks API
description: Needs a description.
paths:
/folder_locks:
get:
operationId: get_folder_locks
summary: Box List folder locks
tags:
- Folder Locks
x-box-tag: folder_locks
x-box-sanitized: true
x-box-enable-explorer: true
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.
parameters:
- name: folder_id
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
required: true
schema:
type: string
nullable: false
responses:
'200':
description: >-
Returns details for all folder locks applied to the folder,
including the
lock type and user that applied the lock.
content:
application/json:
schema:
$ref: '#/components/schemas/FolderLocks'
'403':
description: >-
Returned when the access token provided in the `Authorization`
header
is not recognized or not provided.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: |-
Returned if the folder is not found, or the user does not
have access to the folder.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'405':
description: Returned if the `folder_id` is not in a recognized format.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
post:
operationId: post_folder_locks
summary: Box Create folder lock
tags:
- Folder Locks
x-box-tag: folder_locks
x-box-sanitized: true
x-box-enable-explorer: false
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.
requestBody:
content:
application/json:
schema:
type: object
required:
- folder
properties:
locked_operations:
type: object
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`.
required:
- move
- delete
properties:
move:
type: boolean
description: Whether moving the folder should be locked.
example: true
delete:
type: boolean
description: Whether deleting the folder should be locked.
example: true
folder:
type: object
description: The folder to apply the lock to.
required:
- type
- id
properties:
type:
type: string
description: >-
The content type the lock is being applied to. Only
`folder`
is supported.
example: folder
id:
type: string
description: The ID of the folder.
example: '1234567890'
responses:
'200':
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.
content:
application/json:
schema:
$ref: '#/components/schemas/FolderLock'
'400':
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.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
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.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/folder_locks/{folder_lock_id}:
delete:
operationId: delete_folder_locks_id
summary: Box Delete folder lock
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.
tags:
- Folder Locks
x-box-tag: folder_locks
x-box-sanitized: true
parameters:
- name: folder_lock_id
description: The ID of the folder lock.
example: '12345'
in: path
required: true
schema:
type: string
nullable: false
responses:
'204':
description: >-
Returns an empty response when the folder lock is successfully
deleted.
'403':
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.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
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.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
components:
schemas:
FolderLocks:
title: Folder Locks
type: object
x-box-resource-id: folder_locks
x-box-tag: folder_locks
description: A list of folder locks
properties:
entries:
type: array
description: A list of folder locks
items:
$ref: '#/components/schemas/FolderLock'
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'
type: string
next_marker:
description: The marker for the start of the next page of results.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
type: string
nullable: true
ClientError:
title: Client error
type: object
x-box-resource-id: client_error
description: A generic error
properties:
type:
description: error
example: error
type: string
enum:
- error
nullable: false
status:
description: The HTTP status of the response.
example: 400
type: integer
format: int32
nullable: false
code:
description: A Box-specific error code
example: item_name_invalid
type: string
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
message:
description: A short message describing the error.
example: Method Not Allowed
type: string
nullable: false
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.
type: object
nullable: true
properties:
message:
type: string
description: More details on the error.
example: Something went wrong.
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/
type: string
nullable: false
request_id:
description: |-
A unique identifier for this response, which can be used
when contacting Box support.
type: string
example: abcdef123456
nullable: false
FolderLock:
title: Folder Lock
type: object
x-box-resource-id: folder_lock
x-box-tag: folder_locks
description: |-
Folder locks define access restrictions placed by folder owners
to prevent specific folders from being moved or deleted.
properties:
folder:
allOf:
- $ref: '#/components/schemas/Folder--Mini'
- description: The folder that the lock applies to.
id:
type: string
description: The unique identifier for this folder lock.
example: '12345678'
type:
type: string
description: The object type, always `folder_lock`.
example: folder_lock
created_by:
allOf:
- $ref: '#/components/schemas/User--Base'
- description: The user or group that created the lock.
created_at:
type: string
format: date-time
example: '2020-09-14T23:12:53Z'
description: When the folder lock object was created.
locked_operations:
type: object
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`.
required:
- move
- delete
properties:
move:
type: boolean
description: Whether moving the folder is restricted.
nullable: false
example: true
delete:
type: boolean
description: Whether deleting the folder is restricted.
nullable: false
example: true
lock_type:
type: string
description: The lock type, always `freeze`.
example: freeze
tags:
- name: Folder Locks