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

When setting a native icon, the name field accepts either Notion’s internal API icon name or the name shown in the Notion icon picker tooltip. Responses return the internal API icon name. Icon picker names are case-insensitive, and spaces, underscores, and hyphens are treated equivalently. For example, "token", "star circle", "star-circle", and "STAR_CIRCLE" set the same icon. "redirect", "arrow redirect heavy", and "arrow_redirect_heavy" also set the same icon.

​
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"
    }
  }
}'