---
title: "Notion API Markdown content API and Notion MCP return custom blocks instead of unknown elements: 2026-09-30 | Harbyn"
description: "Notion API Markdown content API and Notion MCP return custom blocks instead of unknown elements, announced Sep 30, 2026."
canonical: "https://harbyn.com/changes/notion/2026-09-30-custom-blocks-in-markdown"
last-updated: 2026-10-06
---

# Notion API Markdown content API and Notion MCP return custom blocks instead of unknown elements

Markdown version of <https://harbyn.com/changes/notion/2026-09-30-custom-blocks-in-markdown>.

Behavior change - Notion API. low severity. In effect.

The markdown content API and Notion MCP now return custom blocks with inherited bindings as a custom-block element with definition-id and url attributes, where they previously returned an unknown element. Existing definitions can be placed and unchanged instances are preserved during page edits; creating definitions remains in private alpha.

## Facts

| Fact | Value |
| --- | --- |
| Vendor | [Notion API](https://harbyn.com/vendors/notion.md) |
| Kind | Behavior change |
| Severity | low |
| Status | In effect |
| Announced | Sep 30, 2026 |
| Added to Harbyn | Oct 6, 2026 |
| Lead time | No dated deadline |
| Review | Reviewed by a person, extracted by a model |

## Find it in your code

```sh
npx harbyn scan
```

This change names no identifier the scanner can match line by line, so the scan tells you whether your repository uses Notion API, from its packages and API hosts. Nothing leaves your machine.

## Sources

Where this event comes from: the page we read, when we read it, and the hash of that snapshot.

- <https://developers.notion.com/page/changelog.md> (changelog, fetched 2026-10-06 00:10 UTC, sha256 `bce6d6fba28177832cc641b9464427397729120de6755e062cbcbe44695e7ab6`)

## Related changes

### More from Notion API

- [Completing the query tool update in Notion MCP](https://harbyn.com/changes/notion/2026-09-29-completing-the-query-tool-update-in-notion-mcp.md) (Retirement, effective Sep 29, 2026)
- [Oversized page edits return HTTP 400](https://harbyn.com/changes/notion/2026-10-02-page-edits-return-400-when-a-page-is-too-large-to-load.md) (Behavior change, announced Oct 2, 2026)
- [Custom emoji icons are validated](https://harbyn.com/changes/notion/2026-09-25-custom-emoji-icons-are-validated.md) (Behavior change, announced Sep 25, 2026)
- [notion-fetch no longer signs file URLs by default](https://harbyn.com/changes/notion/2026-10-05-notion-fetch-no-longer-signs-file-urls-by-default.md) (Breaking change, announced Oct 5, 2026)

### Changes at other vendors

- [Amazon Selling Partner API: ORDER\_CHANGE notifications add PreFulfillmentStatusChange for Amazon Autos](https://harbyn.com/changes/amazon-sp-api/2026-10-14-sp-api-updates-new-listings-items-api-ivp-values-in-eu5-jp-and-ca-stores-oct-3.md) (effective Oct 28, 2026)
- [BigCommerce: 301 redirects will apply only to storefront channels](https://harbyn.com/changes/bigcommerce/2026-10-07-301-redirects-now-apply-to-storefront-channels-only.md) (effective Nov 10, 2026)
- [GitHub: Secret scanning audit log business field changes to enterprise slug](https://harbyn.com/changes/github/2026-10-20-updates-to-github-secret-scanning-7.md) (effective Nov 12, 2026)
- [Jira / Atlassian Cloud: New IP address ranges in use from January 1, 2027](https://harbyn.com/changes/atlassian-jira/2026-10-16-atlassian-cloud-adds-new-ip-address-ranges.md) (effective Jan 1, 2027)

[All upcoming deadlines](https://harbyn.com/deadlines.md)