> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://notion.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://notion.ferndocs.com/_mcp/server.

# Emoji

An emoji object contains information about an emoji character. It is most often used to represent an emoji that is rendered as a page icon in the Notion UI. 

**`Example emoji object`**

```json Example emoji object
{
  "type": "emoji",
  "emoji": "😻"
}
```

The object contains the following fields:

|         | Type      | Description                                                    | Example value |
| :------ | :-------- | :------------------------------------------------------------- | :------------ |
| `type`  | `"emoji"` | The constant string `"emoji"` that represents the object type. | `"emoji"`     |
| `emoji` | `string`  | The emoji character.                                           | `"😻"`        |

To use the Notion API to render an emoji object as a page icon, set a page’s icon [property field](/reference/page) to an emoji object. 

### Example: set a page icon via the [Create a page](/reference/post-page) endpoint

```curl
curl 'https://api.notion.com/v1/pages' \
  -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2022-06-28" \
  --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](/reference/patch-page) endpoint

```curl
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: 2022-06-28" \
  -X PATCH \
	--data '{
  "icon": {
	  "type": "emoji", 
	  "emoji": "🥨"
    }
}'
```

## Custom emoji

Custom emojis are icons uploaded and managed in your own workspace.

The object contains the following fields:

|                | Type             | Description                                                    | Example value                                                                                                                                                                                                           |
| :------------- | :--------------- | :------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`         | `"custom_emoji"` | The constant string `"emoji"` that represents the object type. | `"emoji"`                                                                                                                                                                                                               |
| `custom_emoji` | `object`         | Custom emoji object, containing id, name, url                  | `{       "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: custom emoji in page icon response:

**`Example emoji object`**

```json Example emoji object
{
  "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 response

**`Example emoji object`**

```json Example emoji object
{
  "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 page icon to a custom emoji

Provide the custom emoji ID to preserve/set custom emoji

```curl
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: 2022-06-28" \
  -X PATCH \
  --data '{
  "icon": {
    "type": "custom_emoji",
    "custom_emoji": {
      "id": "45ce454c-d427-4f53-9489-e5d0f3d1db6b"
    }
  }
}'
```