Box Comments API
The Box Comments API provides endpoints for creating, retrieving, updating, and deleting comments on files, enabling users to have threaded discussions and collaborate on content stored in Box.
OpenAPI Specification
openapi: 3.1.0
info:
title: Box Comments API
description: Needs a description.
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:
- Files
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'
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
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.
tags:
- name: Comments
- name: Files