Skip to main content
Emoji and icon objects represent icons on pages, databases, and callout blocks. The icon field is a discriminated union on the type key:
typeReadWriteDescription
"emoji"YesYesA standard emoji character. See Emoji.
"custom_emoji"YesYesA workspace custom emoji, referenced by id. See Custom emoji.
"icon"YesYesA native Notion icon with name and color. See Icon.
"external"YesYesAn externally hosted image URL. See File object.
"file"YesNoA Notion-hosted file (uploaded via the UI). Returned in responses only. See File object.
"file_upload"NoYesA file uploaded via the File Upload API. Write-only. See File object.
The read/write columns above apply to page and database icons. Callout block icons support all types except file_upload on write — use emoji, external, custom_emoji, or icon instead.

​
Emoji

{
  "type": "emoji",
  "emoji": "😻"
}
FieldTypeDescriptionExample value
type"emoji"The constant string "emoji" that represents the object type."emoji"
emojistringThe emoji character."😻"

​
Example: set a page icon via the Create a page endpoint

curl 'https://api.notion.com/v1/pages' \
  -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2026-03-11" \
  --data '{
  "parent": {
    "page_id": "13d6da822f9343fa8ec14c89b8184d5a"
  },
  "properties": {
    "title": [
      {
        "type": "text",
        "text": {
          "content": "A page with an avocado icon",
          "link": null
        }
      }
    ]
  },
  "icon": {
    "type": "emoji",
    "emoji": "🥑"
  }
}'

​
Example: set a page icon via the Update page endpoint

curl https://api.notion.com/v1/pages/60bdc8bd-3880-44b8-a9cd-8a145b3ffbd7 \
  -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2026-03-11" \
  -X PATCH \
	--data '{
  "icon": {
	  "type": "emoji",
	  "emoji": "🥨"
    }
}'

​
Custom emoji

Custom emojis are icons uploaded and managed in your workspace. Use the List custom emojis endpoint to retrieve them.
FieldTypeDescriptionExample value
type"custom_emoji"The constant string "custom_emoji" that represents the object type."custom_emoji"
custom_emojiobjectObject containing id, name, and url.

​
Example: custom emoji in a page icon response

{
  "icon": {
    "type": "custom_emoji",
    "custom_emoji": {
      "id": "45ce454c-d427-4f53-9489-e5d0f3d1db6b",
      "name": "bufo",
      "url": "https://s3-us-west-2.amazonaws.com/public.notion-static.com/865e85fc-7442-44d3-b323-9b03a2111720/3c6796979c50f4aa.png"
    }
  }
}

​
Example: inline custom emoji in rich text

{
  "type": "mention",
  "mention": {
    "type": "custom_emoji",
    "custom_emoji": {
      "id": "45ce454c-d427-4f53-9489-e5d0f3d1db6b",
      "name": "bufo",
      "url": "https://s3-us-west-2.amazonaws.com/public.notion-static.com/865e85fc-7442-44d3-b323-9b03a2111720/3c6796979c50f4aa.png"
    }
  }
}

​
Example: set a page icon to a custom emoji

When writing, only the id field is required inside custom_emoji. 
curl https://api.notion.com/v1/pages/60bdc8bd-3880-44b8-a9cd-8a145b3ffbd7 \
  -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2026-03-11" \
  -X PATCH \
  --data '{
  "icon": {
    "type": "custom_emoji",
    "custom_emoji": {
      "id": "45ce454c-d427-4f53-9489-e5d0f3d1db6b"
    }
  }
}'

​
Example: look up a custom emoji by name

Use the name query parameter on List custom emojis to resolve a custom emoji name to its ID, then use the ID to set a page icon. 
curl 'https://api.notion.com/v1/custom_emojis?name=bufo' \
  -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
  -H "Notion-Version: 2026-03-11"
Example response: 
{
  "object": "list",
  "type": "custom_emoji",
  "results": [
    {
      "id": "45ce454c-d427-4f53-9489-e5d0f3d1db6b",
      "name": "bufo",
      "url": "https://s3-us-west-2.amazonaws.com/public.notion-static.com/865e85fc-7442-44d3-b323-9b03a2111720/3c6796979c50f4aa.png"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

​
Icon

Native Notion icons are built-in icons with a name and color. They appear in the Notion UI icon picker under the “Icons” tab. 
{
  "type": "icon",
  "icon": {
    "name": "pizza",
    "color": "blue"
  }
}
FieldTypeDescriptionExample value
type"icon"The constant string "icon" that represents the object type."icon"
iconobjectAn object with name (required) and color (optional, defaults to "gray"). See below for valid values.

​
Icon name

The name field identifies the icon. Refer to the Notion icon picker for valid names (e.g. "pizza", "meeting", "home").

​
Icon color

Valid color values: "gray", "lightgray", "brown", "yellow", "orange", "green", "blue", "purple", "pink", "red". If omitted when setting an icon, the color defaults to "gray".

​
Example: set a page icon to a native icon

curl https://api.notion.com/v1/pages/60bdc8bd-3880-44b8-a9cd-8a145b3ffbd7 \
  -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2026-03-11" \
  -X PATCH \
  --data '{
  "icon": {
    "type": "icon",
    "icon": {
      "name": "pizza",
      "color": "blue"
    }
  }
}'