View my integrations
Back to All
added

Page icons, cover images, new block types, and improved page file properties

over 2 years ago by Ryan Hart

We have added support for linking to external image and file URLs, and many new block types, including image, embed, and file blocks.

You can now use the Notion API to:

We do not yet support uploading files to Notion through the API, however, any files already uploaded to Notion can be retrieved. You can reference the details of what is supported here.

Page Icons and Cover Images

When fetching a Page object or a Database object, the response will now include an icon and cover property, as shown below:

{
    "object": "database",
    "id": "96433ad8-3fbe-460f-a007-72311c4aa804",
    "cover": {
        "type": "external",
        "external": {
            "url": "https://website.domain/images/image.png"
        }
    },
    "icon": {
        "type": "emoji",
        "emoji": "🎉"
    },
    // ... remaining properties
}

The Create a page, Update page, Create a database, and Update database API endpoints now support the ability to set the page icon and cover image.

New Block Types

You can now can retrieve and add embed, image, video, file, pdf, and bookmark blocks when using Append block children and Retrieve block children.

Below is an example response from Retrieve a page containing an image uploaded to Notion.

{
    "object": "list",
    "results": [
        {
            "object": "block",
            "id": "4896a9bf-ada2-4bec-8ea2-97bccf07c4ef",
            "created_time": "2021-08-20T21:12:00.000Z",
            "last_edited_time": "2021-08-20T21:12:00.000Z",
            "has_children": false,
            "type": "image",
            "image": {
                "caption": [],
                "type": "file",
                "file": {
                    "url": "https://s3.us-west-2.amazonaws.com/secure.notion-static.com/64f658a7-eb31-4f98-8bea-0aa2956ec475/brocolli.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAT73L2G45O3KS52Y5%2F20210820%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20210820T211229Z&X-Amz-Expires=3600&X-Amz-Signature=e2adc496254ccc741d7ab4f3bab0de7a51b60e31a49d11fcf8702ead2ec9ec18&X-Amz-SignedHeaders=host",
                    "expiry_time": "2021-08-20T22:12:29.066Z"
                }
            }
        }
    ],
    "next_cursor": null,
    "has_more": false
}

📘

Third-party App Embeds

Third-party web applications, e.g. Typeform, Figma, etc., are retrieved and added as embed blocks.

File Page Properties

When retrieving file page properties, you'll now get a link to the file as well as the name.

{
    "object": "page",
    "properties": {
        "Files": {
            "id": "YP~`",
            "type": "files",
            "files": [
                {
                    "name": "Brocolli",
                    "type": "file",
                    "file": {
                        "url": "https://s3.us-west-2.amazonaws.com/secure.notion-static.com/c32db351-d1ea-40c2-9660-820db28c44ad/brocolli.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAT73L2G45O3KS52Y5%2F20210820%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20210820T211042Z&X-Amz-Expires=3600&X-Amz-Signature=859a24c9b7153860b252fa5955829a97632650dcdc5e91c7a831a48c5efecae4&X-Amz-SignedHeaders=host",
                        "expiry_time": "2021-08-20T22:10:42.022Z"
                    }
                },
                {
                    "name": "Text File",
                    "type": "external",
                    "external": {
                        "url": "https://website.domain/files/doc.txt"
                    }
                }
            ]
        },
    },
    // ... remaining properties
}

We also support updating file page properties via Update page.