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