# Notion Blocks API

**Canonical:** https://apis.io/apis/notion/notion-blocks-api/  
**Provider:** Notion — https://apis.io/providers/notion/  
**Base URL:** https://api.notion.com/v1  
**Documentation:** https://developers.notion.com

Notion Blocks API is one of 6 APIs that [Notion](https://apis.io/providers/notion/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification and an AsyncAPI event-driven specification. This API exposes 3 JSON Schema definitions. Tagged areas include Blocks. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, an AsyncAPI specification, a JSON-LD context, authentication docs, a getting-started guide, and 3 JSON Schemas.

Blocks are the fundamental units of content in Notion. Every page is composed of blocks, which can be paragraphs, headings, images, tables, lists, and many other types. Blocks can have children, forming a tree structure. Use these endpoints to retrieve, update, delete blocks and manage block children.

## Operations (5)

| Method | Path | Summary |
|---|---|---|
| GET | `/blocks/{block_id}` | Notion Retrieve a block |
| PATCH | `/blocks/{block_id}` | Notion Update a block |
| DELETE | `/blocks/{block_id}` | Notion Delete a block |
| GET | `/blocks/{block_id}/children` | Notion Retrieve block children |
| PATCH | `/blocks/{block_id}/children` | Notion Append block children |

## Machine-readable artifacts (64)

- **OpenAPI** — https://raw.githubusercontent.com/api-evangelist/notion/refs/heads/main/openapi/notion-blocks-api-openapi.yml
- **Documentation** — https://developers.notion.com
- **AsyncAPI** — https://raw.githubusercontent.com/api-evangelist/notion/refs/heads/main/asyncapi/notion-webhooks-asyncapi.yml
- **JSONSchema** — https://raw.githubusercontent.com/api-evangelist/notion/refs/heads/main/json-schema/notion-page-schema.json
- **JSONSchema** — https://raw.githubusercontent.com/api-evangelist/notion/refs/heads/main/json-schema/notion-database-schema.json
- **JSONSchema** — https://raw.githubusercontent.com/api-evangelist/notion/refs/heads/main/json-schema/notion-block-schema.json
- **JSONLD** — https://raw.githubusercontent.com/api-evangelist/notion/refs/heads/main/json-ld/notion-context.jsonld
- **Authentication** — https://developers.notion.com/reference/authentication
- **Authorization** — https://developers.notion.com/docs/authorization
- **GettingStarted** — https://developers.notion.com/docs/getting-started
- **GitHubRepo** — https://github.com/makenotion/notion-sdk-js
- **BaseURL** — https://api.notion.com
- **IntroductionAPI** — https://developers.notion.com/reference/intro
- **DatabaseCreateAPI** — https://developers.notion.com/reference/create-a-database
- **DatabaseRetrieveAPI** — https://developers.notion.com/reference/retrieve-a-database
- **DatabaseUpdateAPI** — https://developers.notion.com/reference/update-a-database
- **DatabaseQueryAPI** — https://developers.notion.com/reference/post-database-query
- **PageCreateAPI** — https://developers.notion.com/reference/post-page
- **PageRetrieveAPI** — https://developers.notion.com/reference/retrieve-a-page
- **PageUpdateAPI** — https://developers.notion.com/reference/patch-page
- **PageTrashAPI** — https://developers.notion.com/reference/archive-a-page
- **PageMoveAPI** — https://developers.notion.com/reference/move-page
- **PagePropertyRetrieveAPI** — https://developers.notion.com/reference/retrieve-a-page-property
- **PageMarkdownRetrieveAPI** — https://developers.notion.com/reference/retrieve-page-markdown
- **PageMarkdownUpdateAPI** — https://developers.notion.com/reference/update-page-markdown
- **BlockRetrieveAPI** — https://developers.notion.com/reference/retrieve-a-block
- **BlockUpdateAPI** — https://developers.notion.com/reference/update-a-block
- **BlockDeleteAPI** — https://developers.notion.com/reference/delete-a-block
- **BlockChildrenRetrieveAPI** — https://developers.notion.com/reference/get-block-children
- **BlockChildrenAppendAPI** — https://developers.notion.com/reference/patch-block-children
- **UsersListAPI** — https://developers.notion.com/reference/get-users
- **UserRetrieveAPI** — https://developers.notion.com/reference/get-user
- **UserBotRetrieveAPI** — https://developers.notion.com/reference/get-self
- **CommentCreateAPI** — https://developers.notion.com/reference/create-a-comment
- **CommentsListAPI** — https://developers.notion.com/reference/list-comments
- **CommentRetrieveAPI** — https://developers.notion.com/reference/retrieve-comment
- **SearchAPI** — https://developers.notion.com/reference/post-search
- **DataSourceCreateAPI** — https://developers.notion.com/reference/create-a-data-source
- **DataSourceRetrieveAPI** — https://developers.notion.com/reference/retrieve-a-data-source
- **DataSourceUpdateAPI** — https://developers.notion.com/reference/update-a-data-source
- …and 24 more, listed in full on the page.

## Other Notion APIs (5)

- [Notion Comments API](https://apis.io/apis/notion/notion-comments-api/)
- [Notion Databases API](https://apis.io/apis/notion/notion-databases-api/)
- [Notion Pages API](https://apis.io/apis/notion/notion-pages-api/)
- [Notion Search API](https://apis.io/apis/notion/notion-search-api/)
- [Notion Users API](https://apis.io/apis/notion/notion-users-api/)

## Tags

Blocks

---

Profiled by [API Evangelist](https://apievangelist.com) and published on [APIs.io](https://apis.io/apis/notion/notion-blocks-api/). The API's provider profile, Kin Score and agent-readiness rating are at https://apis.io/providers/notion/.