Overview

FileObject represents file information shared by file-based blocks and file properties. It is primarily a read-only representation of the file currently held by its owning block or property.

Do not construct or mutate a FileObject directly. Read it through APIs such as block.file_object or a file property's value, and perform updates through the owning block or property.

block = ImageBlock.new "<https://example.com/image.png>"
file = block.file_object

file.type
# => "external"

file.url
# => "<https://example.com/image.png>"

1. Instance methods

type → String

Returns the current Notion file type: "external", "file", or "file_upload".

url → String or nil

Returns the external or Notion-hosted file URL. It returns nil while the object represents a pending FileUploadObject.

<aside> ⚠️

A URL returned for a Notion-hosted file (type == "file") may expire. Retrieve the block or page again when a fresh URL is required.

</aside>

file_upload_object → FileUploadObject or nil

Returns the upload object while the file type is "file_upload". After the owning object is saved and reconstructed from the Notion API response, the type becomes "file" and this method returns nil.

external? → Boolean

Returns true when the current type is "external"; otherwise, returns false.

2. Updating a file

Update files through the owning block or property. Direct setters and JSON conversion methods on FileObject are internal APIs.

block.url = "<https://example.com/new-image.png>"
block.save

FileObject#will_update is no longer available. Update tracking belongs to the owning block or property.