Embeds

On this page, we'll dive into the different embed endpoints you can use to manage embeds programmatically. We'll look at how to query, create, update, and delete embeds.

The embed model

The embed model contains all the information about the embeds in your application.

Properties

Name
id
Type
string
Description
Unique identifier for the embed.
Name
created_at
Type
string
Description
Timestamp of when the embed was created.
Name
embed_url
Type
string
Description
URL of the embed to be used in an iframe.
Name
notion_id
Type
string
Description
Unique identifier for the Notion page.
Name
notion_url
Type
string
Description
Public URL of the Notion page.
Name
mode
Type
string
Description
Mode of the embed. Can be light, dark, auto, or user_defined. auto will follow the user's system settings and user_defined will let the user choose within the embed top bar.
Name
font
Type
string
Description
Font of the embed. Can be default or a Google Font name.
Name
show_top_bar
Type
boolean
Description
Whether to show the top bar of the embed. Setting mode to user_defined will also enable the top bar.

GET/v1/embeds

List all embeds

This endpoint allows you to retrieve a paginated list of all your embeds. By default, a maximum of ten embeds are returned. You can use the first parameter to change the number of embeds returned.

Optional attributes

Name
after
Type
string
Description
Cursor for pagination. This can be used to retrieve the next page of embeds.
Name
first
Type
number
Description
Number of embeds to return. Max: 50. Default: 10.

Request

GET

/v1/embeds

curl -G https://api.embednotionpages.com/v1/embeds \
  -H "Authorization: Bearer {token}" \
  -d limit=10

Response

{
  "embeds": [
    {
      "id": "o2jorkkr549mvy",
      "created_at": "2022-01-01T00:00:00Z",
      "embed_url": "https://o2jorkkr549mvy.embednotionpage.com/Meal-Planner-95747105f402490eba51d52e00496c1c",
      "notion_id": "95747105-f402-490e-ba51-d52e00496c1c",
      "notion_url": "https://www.notion.so/Meal-Planner-95747105f402490eba51d52e00496c1c",
      "mode": "auto",
      "font": "default",
      "show_top_bar": false
    },
    // ... more embeds
  ],
  "total_count": 100,
  "pagination": {
    "end_cursor": "6yo0eo1ro2yqwj",
    "has_next_page": true
  }
}

POST/v1/embeds

Create an embed

This endpoint allows you to add a new embed to your application. Public URL of a Notion page is required to create an embed.

Required attributes

Name
notion_url
Type
string
Description
URL of the Notion page.

Optional attributes

Name
mode
Type
string
Description
Mode of the embed. Can be light, dark, auto, or user_defined. Default: light
Name
font
Type
string
Description
Font of the embed. Can be default or a Google Font name.
Name
show_top_bar
Type
boolean
Description
Whether to show the top bar of the embed. Default: true.

Request

POST

/v1/embeds

curl https://api.embednotionpages.com/v1/embeds \
  -H "Authorization: Bearer {token}" \
  -d 'notion_url'="https://www.notion.so/Meal-Planner-95747105f402490eba51d52e00496c1c"

Response

{
  "embed": {
    "id": "6yo0eo1ro2yqwj",
    "created_at": "2022-01-01T00:00:00Z",
    "embed_url": "https://6yo0eo1ro2yqwj.embednotionpage.com/Meal-Planner-95747105f402490eba51d52e00496c1c",
    "notion_id": "95747105-f402-490e-ba51-d52e00496c1c",
    "notion_url": "https://www.notion.so/Meal-Planner-95747105f402490eba51d52e00496c1c",
    "mode": "dark",
    "font": "default",
    "show_top_bar": true
  }
}

GET/v1/embeds/:id

Retrieve an embed

This endpoint allows you to retrieve an embed by providing the embed id. Refer to the list at the top of this page to see which properties are included with embed objects.

Request

GET

/v1/embeds/6yo0eo1ro2yqwj

curl https://api.embednotionpages.com/v1/embeds/6yo0eo1ro2yqwj \
  -H "Authorization: Bearer {token}"

Response

{
  "embed": {
    "id": "6yo0eo1ro2yqwj",
    "created_at": "2022-01-01T00:00:00Z",
    "embed_url": "https://6yo0eo1ro2yqwj.embednotionpage.com/Meal-Planner-95747105f402490eba51d52e00496c1c",
    "notion_id": "95747105-f402-490e-ba51-d52e00496c1c",
    "notion_url": "https://www.notion.so/Meal-Planner-95747105f402490eba51d52e00496c1c",
    "mode": "dark",
    "font": "default",
    "show_top_bar": true
  }
}

PATCH/v1/embeds/:id

Update an embed

This endpoint allows you to perform an update on an embed. Examples of updates are changing the Notion page id or url, or updating the settings.

Optional attributes

Name
mode
Type
string
Description
Mode of the embed. Can be light, dark, auto, or user_defined.
Name
font
Type
string
Description
Font of the embed.
Name
show_top_bar
Type
boolean
Description
Whether to show the top bar of the embed.

Request

PATCH

/v1/embeds/6yo0eo1ro2yqwj

curl -X PATCH https://api.embednotionpages.com/v1/embeds/6yo0eo1ro2yqwj \
  -H "Authorization: Bearer {token}" \
  -d 'mode'="light" \
  -d 'show_top_bar'="false"

Response

{
  "embed": {
    "id": "6yo0eo1ro2yqwj",
    "created_at": "2022-01-01T00:00:00Z",
    "embed_url": "https://6yo0eo1ro2yqwj.embednotionpage.com/Meal-Planner-95747105f402490eba51d52e00496c1c",
    "notion_id": "95747105-f402-490e-ba51-d52e00496c1c",
    "notion_url": "https://www.notion.so/Meal-Planner-95747105f402490eba51d52e00496c1c",
    "mode": "light",
    "font": "default",
    "show_top_bar": false
  }
}

DELETE/v1/embeds/:id

Delete an embed

This endpoint allows you to delete your embeds.

⚠️ Note: Calling this method will permanently delete the embed.

Request

DELETE

/v1/embeds/6yo0eo1ro2yqwj

curl -X DELETE https://api.embednotionpages.com/v1/embeds/6yo0eo1ro2yqwj \
  -H "Authorization: Bearer {token}"

Response

{
  "message": "Embed deleted successfully"
}