Box Folder Locks API

openapi: 3.2.0
info:
  title: Box Platform Folder Locks API
  description: Box Platform provides functionality to provide access to content stored within Box. 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.
  termsOfService: https://cloud.app.box.com/s/rmwxu64h1ipr41u49w3bbuvbsa29wku9
  contact:
    name: Box, Inc
    url: https://developer.box.com
    email: devrel@box.com
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: '2024.0'
  x-box-commit-hash: 53bdced3cd
servers:
- url: https://api.box.com/2.0
  description: Box Platform API server.
security:
- OAuth2Security: []
tags:
- name: Folder Locks
  description: Folder locks define access restrictions placed by folder owners to prevent specific folders from being moved or deleted.
  x-box-tag: folder_locks
paths:
  /folder_locks:
    get:
      operationId: get_folder_locks
      summary: List folder locks
      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
        in: query
        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`.'
        required: true
        schema:
          type: string
        example: '12345'
      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'
      x-box-tag: folder_locks
      tags:
      - Folder Locks
      x-codeSamples:
      - lang: curl
        label: List folder locks
        source: "curl -i -X GET \"https://api.box.com/2.0/folder_locks?folder_id=33552487093\" \\\n     -H \"authorization: Bearer <ACCESS_TOKEN>\""
      - lang: dotnet
        label: List folder locks
        source: 'await client.FolderLocks.GetFolderLocksAsync(queryParams: new GetFolderLocksQueryParams(folderId: folder.Id));'
      - lang: swift
        label: List folder locks
        source: 'try await client.folderLocks.getFolderLocks(queryParams: GetFolderLocksQueryParams(folderId: folder.id))'
      - lang: java
        label: List folder locks
        source: client.getFolderLocks().getFolderLocks(new GetFolderLocksQueryParams(folder.getId()))
      - lang: node
        label: List folder locks
        source: "await client.folderLocks.getFolderLocks({\n  folderId: folder.id,\n} satisfies GetFolderLocksQueryParams);"
      - lang: python
        label: List folder locks
        source: client.folder_locks.get_folder_locks(folder.id)
    post:
      operationId: post_folder_locks
      summary: Create folder lock
      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
              properties:
                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`.
                  type: object
                  properties:
                    move:
                      description: Whether moving the folder should be locked.
                      type: boolean
                      example: true
                    delete:
                      description: Whether deleting the folder should be locked.
                      example: true
                      type: boolean
                  required:
                  - move
                  - delete
                folder:
                  description: The folder to apply the lock to.
                  type: object
                  properties:
                    type:
                      description: The content type the lock is being applied to. Only `folder` is supported.
                      type: string
                      example: folder
                    id:
                      description: The ID of the folder.
                      type: string
                      example: '1234567890'
                  required:
                  - type
                  - id
              required:
              - folder
      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'
      x-box-tag: folder_locks
      tags:
      - Folder Locks
      x-box-enable-explorer: false
      x-codeSamples:
      - lang: curl
        label: Create folder lock
        source: "curl -i -X POST \"https://api.box.com/2.0/folder_locks\" \\\n     -H \"authorization: Bearer <ACCESS_TOKEN>\" \\\n     -H \"content-type: application/json\" \\\n     -d '{\n       \"folder\": {\n         \"type\": \"folder\",\n         \"id\": \"33552487093\"\n       },\n       \"locked_operations\": {\n         \"move\": true,\n         \"delete\": true\n       }\n     }'"
      - lang: dotnet
        label: Create folder lock
        source: 'await client.FolderLocks.CreateFolderLockAsync(requestBody: new CreateFolderLockRequestBody(folder: new CreateFolderLockRequestBodyFolderField(id: folder.Id, type: "folder")) { LockedOperations = new CreateFolderLockRequestBodyLockedOperationsField(move: true, delete: true) });'
      - lang: swift
        label: Create folder lock
        source: 'try await client.folderLocks.createFolderLock(requestBody: CreateFolderLockRequestBody(folder: CreateFolderLockRequestBodyFolderField(id: folder.id, type: "folder"), lockedOperations: CreateFolderLockRequestBodyLockedOperationsField(move: true, delete: true)))'
      - lang: java
        label: Create folder lock
        source: client.getFolderLocks().createFolderLock(new CreateFolderLockRequestBody.Builder(new CreateFolderLockRequestBodyFolderField("folder", folder.getId())).lockedOperations(new CreateFolderLockRequestBodyLockedOperationsField(true, true)).build())
      - lang: node
        label: Create folder lock
        source: "await client.folderLocks.createFolderLock({\n  folder: {\n    id: folder.id,\n    type: 'folder',\n  } satisfies CreateFolderLockRequestBodyFolderField,\n  lockedOperations: {\n    move: true,\n    delete: true,\n  } satisfies CreateFolderLockRequestBodyLockedOperationsField,\n} satisfies CreateFolderLockRequestBody);"
      - lang: python
        label: Create folder lock
        source: "client.folder_locks.create_folder_lock(\n    CreateFolderLockFolder(id=folder.id, type=\"folder\"),\n    locked_operations=CreateFolderLockLockedOperations(move=True, delete=True),\n)"
  /folder_locks/{folder_lock_id}:
    delete:
      operationId: delete_folder_locks_id
      summary: 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.'
      parameters:
      - name: folder_lock_id
        in: path
        description: The ID of the folder lock.
        required: true
        schema:
          type: string
        example: '12345'
      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'
      x-box-tag: folder_locks
      tags:
      - Folder Locks
      x-codeSamples:
      - lang: curl
        label: Delete folder lock
        source: "curl -i -X DELETE \"https://api.box.com/2.0/folder_locks/93134\" \\\n     -H \"authorization: Bearer <ACCESS_TOKEN>\""
      - lang: dotnet
        label: Delete folder lock
        source: 'await client.FolderLocks.DeleteFolderLockByIdAsync(folderLockId: NullableUtils.Unwrap(folderLock.Id));'
      - lang: swift
        label: Delete folder lock
        source: 'try await client.folderLocks.deleteFolderLockById(folderLockId: folderLock.id!)'
      - lang: java
        label: Delete folder lock
        source: client.getFolderLocks().deleteFolderLockById(folderLock.getId())
      - lang: node
        label: Delete folder lock
        source: await client.folderLocks.deleteFolderLockById(folderLock.id!);
      - lang: python
        label: Delete folder lock
        source: client.folder_locks.delete_folder_lock_by_id(folder_lock.id)
components:
  schemas:
    Folder--Mini:
      description: A mini representation of a file version, used when nested under another resource.
      type: object
      allOf:
      - $ref: '#/components/schemas/Folder--Base'
      - properties:
          sequence_id:
            allOf:
            - type:
              - string
              - 'null'
              example: '3'
              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.'
            - {}
          name:
            description: The name of the folder.
            type: string
            example: Contracts
      title: Folder (Mini)
      x-box-resource-id: folder--mini
      x-box-tag: folders
      x-box-variant: mini
    ClientError:
      description: A generic error.
      type: object
      properties:
        type:
          description: The value will always be `error`.
          type: string
          example: error
          enum:
          - error
        status:
          description: The HTTP status of the response.
          type: integer
          format: int32
          example: 400
        code:
          description: A Box-specific error code.
          type: string
          example: item_name_invalid
          enum:
          - created
          - accepted
          - no_content
          - redirect
          - not_modified
          - bad_request
          - unauthorized
          - forbidden
          - not_found
          - method_not_allowed
          - conflict
          - precondition_failed
          - unprocessable_entity
          - too_many_requests
          - internal_server_error
          - unavailable
          - item_name_invalid
          - insufficient_scope
        message:
          description: A short message describing the error.
          type: string
          example: Method Not Allowed
        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
          - 'null'
          example:
            message: Something went wrong
          additionalProperties: {}
        help_url:
          description: A URL that links to more information about why this error occurred.
          type: string
          example: https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/
        request_id:
          description: A unique identifier for this response, which can be used when contacting Box support.
          type: string
          example: abcdef123456
      title: Client error
      x-box-resource-id: client_error
    Folder--Base:
      description: The bare basic representation of a folder, the minimal amount of fields returned when using the `fields` query parameter.
      type: object
      properties:
        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`.'
          type: string
          example: '12345'
        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.
          type:
          - string
          - 'null'
          example: '1'
        type:
          description: The value will always be `folder`.
          type: string
          example: folder
          enum:
          - folder
      required:
      - id
      - type
      title: Folder (Base)
      x-box-resource-id: folder--base
      x-box-tag: folders
      x-box-variant: base
      x-box-variants:
      - base
      - mini
      - standard
      - full
    FolderLock:
      description: Folder locks define access restrictions placed by folder owners to prevent specific folders from being moved or deleted.
      type: object
      properties:
        folder:
          allOf:
          - $ref: '#/components/schemas/Folder--Mini'
          - description: The folder that the lock applies to.
        id:
          description: The unique identifier for this folder lock.
          type: string
          example: '12345678'
        type:
          description: The object type, always `folder_lock`.
          type: string
          example: folder_lock
        created_by:
          allOf:
          - $ref: '#/components/schemas/User--Base'
          - description: The user or group that created the lock.
        created_at:
          description: When the folder lock object was created.
          type: string
          format: date-time
          example: '2020-09-14T23:12:53Z'
        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`.
          type: object
          properties:
            move:
              description: Whether moving the folder is restricted.
              type: boolean
              example: true
            delete:
              description: Whether deleting the folder is restricted.
              example: true
              type: boolean
          required:
          - move
          - delete
        lock_type:
          description: The lock type, always `freeze`.
          type: string
          example: freeze
      title: Folder Lock
      x-box-resource-id: folder_lock
      x-box-tag: folder_locks
    FolderLocks:
      description: A list of folder locks.
      type: object
      properties:
        entries:
          description: A list of folder locks.
          type: array
          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.
          type: string
          example: '1000'
        next_marker:
          description: The marker for the start of the next page of results.
          type:
          - string
          - 'null'
          example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
      title: Folder Locks
      x-box-resource-id: folder_locks
      x-box-tag: folder_locks
    User--Base:
      description: A mini representation of a user, used when nested within another resource.
      type: object
      properties:
        id:
          description: The unique identifier for this user.
          type: string
          example: '11446498'
        type:
          description: The value will always be `user`.
          type: string
          example: user
          enum:
          - user
      required:
      - type
      - id
      title: User (Base)
      x-box-resource-id: user--base
      x-box-tag: users
      x-box-variant: base
      x-box-variants:
      - base
      - mini
      - standard
      - full
  securitySchemes:
    OAuth2Security:
      type: oauth2
      description: The access token received from the authorization server in the OAuth 2.0 flow.
      flows:
        authorizationCode:
          authorizationUrl: https://account.box.com/api/oauth2/authorize
          tokenUrl: https://api.box.com/oauth2/token
          scopes:
            root_readonly: Read all files and folders stored in Box
            root_readwrite: Read and write all files and folders stored in Box
            manage_app_users: Provision and manage app users
            manage_managed_users: Provision and manage managed users
            manage_groups: Manage an enterprise's groups
            manage_webhook: Create webhooks programmatically through the API
            manage_enterprise_properties: Manage enterprise properties
            manage_data_retention: Manage data retention polices
            manage_legal_hold: Manage Legal Holds
externalDocs:
  description: Box Developer Documentation.
  url: https://developer.box.com
x-mint:
  mcp:
    enabled: true
x-provenance:
  method: harvested
  publisher: Box
  source: https://developer.box.com/box-openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)