Skip to main content
POST
/
comments
cURL
curl -i -X POST "https://api.box.com/2.0/comments" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "message": "Review completed!",
       "item": {
         "type": "file",
         "id": 426436
       }
     }'
{
  "id": "11446498",
  "type": "comment",
  "is_reply_comment": true,
  "message": "@Aaron Levie these tigers are cool!",
  "created_by": {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "[email protected]"
  },
  "created_at": "2012-12-12T10:53:43-08:00",
  "modified_at": "2012-12-12T10:53:43-08:00",
  "item": {
    "id": "11446498",
    "type": "file"
  },
  "tagged_message": "@[1234567:Aaron Levie] these tigers are cool!"
}
This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.Learn more about Box SDK versioning strategy.

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Query Parameters

​
fields
string[]

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.

Body

application/json
​
message
string
required

The text of the comment.

To mention a user, use the tagged_message parameter instead.

Example:

"Review completed!"

​
item
object
required

The item to attach the comment to.

​
tagged_message
string

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!"

Response

Returns the newly created comment object.

Not all available fields are returned by default. Use the fields query parameter to explicitly request any specific fields.

Comments are messages created on files. Comments can be made independently or created as responses to other comments. Standard representation of a comment. Base representation of a comment.

​
id
string

The unique identifier for this comment.

Example:

"11446498"

​
type
enum<string>

The value will always be comment.

Available options:
comment
Example:

"comment"

​
is_reply_comment
boolean

Whether or not this comment is a reply to another comment.

Example:

true

​
message
string

The text of the comment, as provided by the user.

Example:

"@Aaron Levie these tigers are cool!"

​
created_by
User (Mini) · object

A mini user object representing the author of the comment.

​
created_at
string<date-time>

The time this comment was created.

Example:

"2012-12-12T10:53:43-08:00"

​
modified_at
string<date-time>

The time this comment was last modified.

Example:

"2012-12-12T10:53:43-08:00"

​
item
Reference · object

The file this comment was placed on.

​
tagged_message
string

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.

Example:

"@[1234567:Aaron Levie] these tigers are cool!"