View my integrations
Back to All

Synced Block, Link to Page and Template block types are now supported in the API

over 2 years ago by MJ Felix

We have added support for adding and retrieving synced_block, link_to_page and template block types.

Synced_block block type

Similar to the UI, there are two versions of a synced_block -- the original block that was created first and doesn't yet sync with anything else, and the reference blocks that are synced to the original synced block.

Original Synced Block
To create a synced_block, the developer needs to create an original synced block. Developers will be able to identify the original synced_block because it does not "sync_from" any other block (i.e. the synced_from property is set to null).

This is an example of an "original" synced_block. Note that all of the blocks available to be synced in another synced_block are captured in the children property.

{
    "type": "synced_block",
    "synced_block": {
        "synced_from": null,
        "children": [
            {
                "callout": {
                    "text": [
                        {
                            "type": "text",
                            "text": {
                                "content": "Callout in synced block"
                            }
                        }
                    ]
                }
            }
        ]
    }
}

Reference Synced Blocks
To sync the content of the original synced_block with another synced_block, the developer simply needs to refer to that synced_block using the synced_from property.

Below is an example of a synced_block referring to another synced_block. Note that only "original" synced blocks can be referenced in the synced_from property.

{
    "type": "synced_block",
    "synced_block": {
        "synced_from": {
            "block_id": "original_synced_block_id"
        }
    }
}

Below is the example response after creating the synced_block above. We can tell that the content from the original synced block is synced with this one because this block has children even though we didn't explicitly set the children in the body of our API call above (i.e. has_children property on the reference block is true).

{
    "object": "list",
    "results": [
        {
            "object": "block",
            "id": "block_id",
            "created_time": "2021-11-17T22:17:00.000Z",
            "last_edited_time": "2021-11-17T22:17:00.000Z",
            "has_children": true,
            "archived": false,
            "type": "synced_block",
            "synced_block": {
                "synced_from": {
                    "type": "block_id",
                    "block_id": "original_synced_block_id"
                }
            }
        }
    ],
    "next_cursor": null,
    "has_more": false
}

🚧

Important notes

  1. The bot must have access to both the original and reference synced blocks
  2. Similar to the UI, we don't support changes to synced_from at this time

Link to Page block type

We have added support for adding and retrieving link_to_page block types. Using this block type, developers can now create page links to other pages (using the page_id property) and full page databases (using the database_id property).

Below is an example request body for the append block children endpoint containing a link_to_page block type.

{
    "children": [
        {
            "type": "link_to_page",
            "link_to_page": {
                "type": "page_id",
                "page_id": "61cca5bd-c8c6-4fcc-b517-514da3b8b1e0"
            }
        }
    ]
}

Template block type

We have added support for adding and retrieving template block types. Using this block type, developers can now create template that duplicates the its children blocks.

Below is an example request body for the append block children endpoint containing a template block type.

{
    "children": [
        {
            "type": "template",
            "template": {
                "text": [
                    {
                        "type": "text",
                        "text": {
                            "content": "Create callout template"
                        }
                    }
                ],
                "children": [
                    {
                        "callout": {
                            "text": [
                                {
                                    "type": "text",
                                    "text": {
                                        "content": "Placeholder callout text"
                                    }
                                }
                            ]
                        }
                    }
                ]
            }
        }
    ]
}