Box Folder Locks API

openapi: 3.1.0
info:
  version: "1.0"
  title: Box Authorize Authorization Folder Locks API
  description: Needs a description.
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: 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\naccess to perform the action.\n\n* `access_denied_insufficient_permissions`: Returned when the\n  user does not have access to the folder.\n\n* `insufficient_scope`: Returned an error if the application\n  does not have the right scope to delete folders. Make sure\n  your application has been configured to read and write all files\n  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,\nor the authenticated user does not have access to the folder.\n\n* `not_found` when the authenticated user does not have access\n  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:
    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
    Folder--Base:
      title: Folder (Base)
      type: object
      x-box-resource-id: folder--base
      x-box-sanitized: true
      x-box-tag: folders
      x-box-variants:
      - base
      - mini
      - standard
      - full
      x-box-variant: base
      description: 'The bare basic representation of a folder, the minimal

        amount of fields returned when using the `fields` query

        parameter.'
      required:
      - id
      - type
      properties:
        id:
          type: string
          nullable: false
          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'
        etag:
          type: string
          nullable: true
          example: '1'
          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:
          type: string
          description: '`folder`'
          example: folder
          enum:
          - folder
          nullable: false
    User--Base:
      title: User (Base)
      type: object
      x-box-resource-id: user--base
      x-box-tag: users
      x-box-variants:
      - base
      - mini
      - standard
      - full
      x-box-variant: base
      description: 'A mini representation of a user, used when

        nested within another resource.'
      required:
      - type
      - id
      properties:
        id:
          type: string
          description: The unique identifier for this user
          example: '11446498'
        type:
          type: string
          description: '`user`'
          example: user
          nullable: false
          enum:
          - user
    Folder--Mini:
      title: Folder (Mini)
      type: object
      x-box-resource-id: folder--mini
      x-box-variant: mini
      description: 'A mini representation of a file version, used when

        nested under another resource.'
      allOf:
      - $ref: '#/components/schemas/Folder--Base'
      - properties:
          sequence_id:
            allOf:
            - type: string
              example: '3'
              nullable: true
              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.'
            - nullable: false
          name:
            type: string
            description: The name of the folder.
            example: Contracts
            nullable: false
    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