Box Comments API

openapi: 3.1.0
info:
  version: "1.0"
  title: Box Authorize Authorization Comments API
  description: Needs a description.
tags:
- name: Comments
  description: 'Comments are messages generated users on files,

    allowing users to collaborate on a file,

    discussing any feedback they might

    have on the content.'
  x-box-tag: comments
paths:
  /files/{file_id}/comments:
    get:
      operationId: get_files_id_comments
      summary: Box List file comments
      description: Retrieves a list of comments for a file.
      tags:
      - Comments
      x-box-tag: comments
      parameters:
      - name: file_id
        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
        required: true
        schema:
          type: string
      - name: fields
        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.'
        in: query
        example:
        - id
        - type
        - name
        required: false
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: limit
        description: The maximum number of items to return per page.
        in: query
        required: false
        example: 1000
        schema:
          type: integer
          format: int64
          maximum: 1000
      - name: offset
        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.'
        in: query
        required: false
        example: 1000
        schema:
          type: integer
          format: int64
          default: 0
      responses:
        '200':
          description: 'Returns a collection of comment objects. If there are no

            comments on this file an empty collection will be returned.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comments'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /comments/{comment_id}:
    get:
      operationId: get_comments_id
      summary: Box Get comment
      tags:
      - Comments
      x-box-tag: comments
      description: 'Retrieves the message and metadata for a specific comment, as well

        as information on the user who created the comment.'
      parameters:
      - name: comment_id
        description: The ID of the comment.
        example: '12345'
        in: path
        required: true
        schema:
          type: string
      - name: fields
        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.'
        in: query
        example:
        - id
        - type
        - name
        required: false
        explode: false
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: Returns a full comment object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comment--Full'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
    put:
      operationId: put_comments_id
      summary: Box Update comment
      tags:
      - Comments
      x-box-tag: comments
      description: Update the message of a comment.
      parameters:
      - name: comment_id
        description: The ID of the comment.
        example: '12345'
        in: path
        required: true
        schema:
          type: string
      - name: fields
        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.'
        in: query
        example:
        - id
        - type
        - name
        required: false
        explode: false
        schema:
          type: array
          items:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                  description: The text of the comment to update
                  example: Review completed!
      responses:
        '200':
          description: Returns the updated comment object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comment--Full'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
    delete:
      operationId: delete_comments_id
      summary: Box Remove comment
      tags:
      - Comments
      x-box-tag: comments
      description: Permanently deletes a comment.
      parameters:
      - name: comment_id
        description: The ID of the comment.
        example: '12345'
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Returns an empty response when the comment has been deleted.
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /comments:
    post:
      operationId: post_comments
      tags:
      - Comments
      x-box-tag: comments
      summary: Box Create comment
      description: 'Adds a comment by the user to a specific file, or

        as a reply to an other comment.'
      parameters:
      - name: fields
        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.'
        in: query
        example:
        - id
        - type
        - name
        required: false
        explode: false
        schema:
          type: array
          items:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - message
              - item
              properties:
                message:
                  type: string
                  description: 'The text of the comment.


                    To mention a user, use the `tagged_message`

                    parameter instead.'
                  example: Review completed!
                tagged_message:
                  type: string
                  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!'
                item:
                  type: object
                  description: The item to attach the comment to.
                  required:
                  - id
                  - type
                  properties:
                    id:
                      type: string
                      description: The ID of the item
                      example: '11446498'
                    type:
                      type: string
                      description: The type of the item that this comment will be placed on.
                      example: file
                      enum:
                      - file
                      - comment
      responses:
        '201':
          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.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comment--Full'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
components:
  schemas:
    Comments:
      title: Comments
      type: object
      x-box-resource-id: comments
      x-box-tag: comments
      description: A list of comments
      allOf:
      - type: object
        description: The part of an API response that describes pagination
        properties:
          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
            type: integer
            format: int64
          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: integer
            format: int64
          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
            type: integer
            format: int64
          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.'
            type: array
            items:
              type: object
              description: The order in which a pagination is ordered
              properties:
                by:
                  description: The field to order by
                  example: type
                  type: string
                direction:
                  type: string
                  description: The direction to order by, either ascending or descending
                  example: ASC
                  enum:
                  - ASC
                  - DESC
      - properties:
          entries:
            type: array
            description: A list of comments
            items:
              $ref: '#/components/schemas/Comment--Full'
    Comment:
      title: Comment
      type: object
      description: Standard representation of a comment.
      x-box-resource-id: comment
      x-box-variant: standard
      allOf:
      - $ref: '#/components/schemas/Comment--Base'
      - properties:
          is_reply_comment:
            type: boolean
            description: 'Whether or not this comment is a reply to another

              comment'
            example: true
          message:
            type: string
            example: '@Aaron Levie these tigers are cool!'
            description: The text of the comment, as provided by the user
          created_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: 'A mini user object representing the author of the

                comment'
          created_at:
            type: string
            format: date-time
            description: The time this comment was created
            example: '2012-12-12T10:53:43-08:00'
          modified_at:
            type: string
            format: date-time
            description: The time this comment was last modified
            example: '2012-12-12T10:53:43-08:00'
          item:
            allOf:
            - title: Reference
              description: The bare basic reference for an object
              type: object
              properties:
                id:
                  type: string
                  description: The unique identifier for this object
                  example: '11446498'
                type:
                  type: string
                  description: The type for this object
                  example: file
            - description: The file this comment was placed on
    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
    User--Mini:
      title: User (Mini)
      type: object
      x-box-resource-id: user--mini
      x-box-variant: mini
      description: 'A mini representation of a user, as can be returned when nested within other

        resources.'
      allOf:
      - $ref: '#/components/schemas/User--Base'
      - properties:
          name:
            type: string
            description: The display name of this user
            example: Aaron Levie
            maxLength: 50
            nullable: false
          login:
            type: string
            format: email
            description: The primary email address of this user
            example: ceo@example.com
            nullable: false
    Comment--Full:
      title: Comment (Full)
      type: object
      x-box-resource-id: comment--full
      x-box-variant: full
      description: 'Comments are messages created on files. Comments

        can be made independently or created as responses to other

        comments'
      allOf:
      - $ref: '#/components/schemas/Comment'
      - properties:
          tagged_message:
            type: string
            example: '@[1234567:Aaron Levie] these tigers are cool!'
            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.'
    Comment--Base:
      title: Comment (Base)
      type: object
      x-box-resource-id: comment--base
      x-box-sanitized: true
      x-box-tag: comments
      x-box-variants:
      - base
      - standard
      - full
      x-box-variant: base
      description: Base representation of a comment.
      properties:
        id:
          type: string
          description: The unique identifier for this comment.
          example: '11446498'
        type:
          type: string
          description: '`comment`'
          example: comment
          enum:
          - comment
    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