Comment attachment

Comments can currently support up to 3 attachments.

Request format (input)

Object properties

After following the Working with files and media guide, provide an array of objects under the attachments parameter in the Create comment API, each containing the following properties:

Parameter	Type	Description	Example value
`file_upload_id`	`string` (UUID)	ID of a File Upload with a status of `"uploaded"`	`"2e2cdb8b-9897-4a6c-a935-82922b1cfb87"`
`type`	`string` (optional)	Possible type values are:`"file_upload"`	`"file_upload"`

Example Create Comment request:

{
  "parent": {
    "page_id": "d0a1ffaf-a4d8-4acf-a1ed-abae6e110418"
  },
  "rich_text": [
    {
      "text": {"content": "Thanks for the helpful page!"}
    },
  ],
  "attachments": {
    "file_upload_id": "2e2cdb8b-9897-4a6c-a935-82922b1cfb87"
  }
}

In the Notion app, when viewing a comment uploaded using the API, the user experience is automatically customized based on the detected category of the file upload. For example, uploading a .png file displays your attachment as an inline image instead of a regular file download block.

Response format (output)

Object properties

The response of Comment APIs like Create comment contains attachments with the following fields:

Field	Type	Description	Example value
`category`	`string` (enum)	The category of this attachment. Possible type values are: `"audio"`, `"image"`, `"pdf"`, `"productivity"`, and `"video"`	`"audio"`
`file`	`object`	A file object containing type-specific configuration.	`{"url": "<https://s3.us-west-2.amazonaws.com/...">, "expiry_time": "2025-06-10T21:26:03.070Z"}`

Example attachment object in Create Comment response:

{
  "category": "video",
  "file": {
    "url": "https://s3.us-west-2.amazonaws.com/...",
    "expiry_time": "2025-06-10T21:26:03.070Z"
  }
}

The file.url is a temporary download link generated at the time of retrieving a comment. See the guide on Retrieving existing files to learn more about accessing the files you upload.

Attachments that are still uploading

When someone attaches a file to a comment in the Notion app, Notion saves the comment before the file finishes uploading. Until the upload finishes, the file isn’t listed in attachments, and the comment’s has_pending_attachments field is true. When the upload finishes, Notion sends a comment.updated webhook event for the comment. Retrieve the comment again to get the file. If the upload fails, the file is removed from the comment, and Notion sends comment.updated, or comment.deleted if the comment has no text. Comments created with the API aren’t affected, because the Create comment API only accepts files that have finished uploading.

Notion API

Objects

Endpoints

Webhook events

Request format (input)

Object properties

Response format (output)

Object properties

Attachments that are still uploading

​Request format (input)

​Object properties

​Response format (output)

​Object properties

​Attachments that are still uploading

Request format (input)

Object properties

Response format (output)

Object properties

Attachments that are still uploading