openapi: 3.1.0
info:
title: Notion Blocks Pages API
description: The Notion API allows developers to integrate with Notion workspaces programmatically. Build integrations that connect Notion with other tools, automate workflows, and manage workspace content including pages, databases, blocks, users, comments, and search. Notion is an all-in-one workspace that combines notes, tasks, wikis, and databases into a flexible, collaborative platform.
version: 2022-06-28
contact:
name: Notion Labs Inc.
email: developers@makenotion.com
url: https://developers.notion.com
license:
name: Notion Developer Terms
url: https://www.notion.so/Developer-Terms-ba4131408d0844e08330da2cbb225c20
termsOfService: https://www.notion.so/terms
servers:
- url: https://api.notion.com/v1
description: Notion API Production Server
security:
- bearerAuth: []
tags:
- name: Pages
description: Pages represent documents in Notion workspaces. They can exist as standalone pages or as entries within a database. Pages contain properties (metadata) and content composed of blocks. Use these endpoints to create, retrieve, update, archive, and manage page properties and content.
externalDocs:
url: https://developers.notion.com/reference/page
paths:
/pages:
post:
operationId: createPage
summary: Notion Create a page
description: Creates a new page that is a child of an existing page or database. If the parent is a database, the property values of the new page must conform to the parent database's schema. The request body must include a parent and properties. Page content can optionally be provided as an array of block objects in the children field.
tags:
- Pages
externalDocs:
url: https://developers.notion.com/reference/post-page
parameters:
- $ref: '#/components/parameters/NotionVersion'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- parent
- properties
properties:
parent:
$ref: '#/components/schemas/Parent'
properties:
type: object
description: Property values for the new page. Keys are property names or IDs. If the parent is a database, the values must conform to the database schema.
additionalProperties: true
children:
type: array
description: Page content as an array of block objects.
items:
$ref: '#/components/schemas/Block'
icon:
description: Page icon, either an emoji or external URL.
oneOf:
- $ref: '#/components/schemas/Emoji'
- $ref: '#/components/schemas/ExternalFile'
cover:
$ref: '#/components/schemas/ExternalFile'
description: Page cover image as an external URL.
responses:
'200':
description: Page successfully created.
content:
application/json:
schema:
$ref: '#/components/schemas/Page'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
/pages/{page_id}:
get:
operationId: retrievePage
summary: Notion Retrieve a page
description: Retrieves a Page object using the ID specified in the path. Returns page properties but not page content (blocks). To retrieve page content, use the retrieve block children endpoint on the page ID.
tags:
- Pages
externalDocs:
url: https://developers.notion.com/reference/retrieve-a-page
parameters:
- $ref: '#/components/parameters/NotionVersion'
- name: page_id
in: path
required: true
description: The ID of the page to retrieve.
schema:
type: string
format: uuid
- name: filter_properties
in: query
required: false
description: A list of page property value IDs to include in the response. If provided, only the specified properties will be returned.
schema:
type: array
items:
type: string
responses:
'200':
description: Page successfully retrieved.
content:
application/json:
schema:
$ref: '#/components/schemas/Page'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
patch:
operationId: updatePage
summary: Notion Update page properties
description: Updates the properties of a page. Only the properties specified in the request body will be updated. Properties that are not included will remain unchanged. Can also update the page icon, cover, and archived status.
tags:
- Pages
externalDocs:
url: https://developers.notion.com/reference/patch-page
parameters:
- $ref: '#/components/parameters/NotionVersion'
- name: page_id
in: path
required: true
description: The ID of the page to update.
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
properties:
type: object
description: Property values to update.
additionalProperties: true
archived:
type: boolean
description: Set to true to archive (trash) the page.
icon:
description: Page icon to set.
oneOf:
- $ref: '#/components/schemas/Emoji'
- $ref: '#/components/schemas/ExternalFile'
- type: 'null'
cover:
oneOf:
- $ref: '#/components/schemas/ExternalFile'
- type: 'null'
description: Page cover image to set or remove.
responses:
'200':
description: Page successfully updated.
content:
application/json:
schema:
$ref: '#/components/schemas/Page'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
/pages/{page_id}/properties/{property_id}:
get:
operationId: retrievePageProperty
summary: Notion Retrieve a page property item
description: Retrieves a property item from a page. For paginated properties like rich text, relation, rollup, and people, this endpoint returns a paginated list. For all other property types, it returns a single property item.
tags:
- Pages
externalDocs:
url: https://developers.notion.com/reference/retrieve-a-page-property
parameters:
- $ref: '#/components/parameters/NotionVersion'
- name: page_id
in: path
required: true
description: The ID of the page.
schema:
type: string
format: uuid
- name: property_id
in: path
required: true
description: The ID of the property to retrieve.
schema:
type: string
- name: start_cursor
in: query
required: false
description: Pagination cursor for paginated property types. If supplied, returns results starting after the cursor.
schema:
type: string
- name: page_size
in: query
required: false
description: Maximum number of property items to return (max 100).
schema:
type: integer
maximum: 100
responses:
'200':
description: Property item successfully retrieved.
content:
application/json:
schema:
type: object
description: A property item object or a paginated list of property items, depending on the property type.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
components:
responses:
Unauthorized:
description: The bearer token is missing, invalid, or the integration lacks access.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
RateLimited:
description: The request has been rate limited. Notion enforces rate limits of 3 requests per second for integrations. Retry after the specified delay.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
headers:
Retry-After:
description: The number of seconds to wait before retrying.
schema:
type: integer
BadRequest:
description: The request was invalid or malformed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: The requested resource does not exist or the integration lacks access to it.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Emoji:
type: object
description: An emoji icon object.
properties:
type:
type: string
const: emoji
description: Always "emoji".
emoji:
type: string
description: The emoji character.
required:
- type
- emoji
File:
type: object
description: A File object represents a file in Notion. Files can be either hosted by Notion (type "file") or externally hosted (type "external").
properties:
type:
type: string
description: The type of file hosting.
enum:
- file
- external
file:
type: object
description: Notion-hosted file details. Present when type is "file". These URLs expire after one hour.
properties:
url:
type: string
format: uri
description: The authenticated S3 URL for the file.
expiry_time:
type: string
format: date-time
description: The expiration time of the URL.
external:
type: object
description: External file details. Present when type is "external".
properties:
url:
type: string
format: uri
description: The URL of the externally hosted file.
name:
type: string
description: The name of the file.
caption:
type: array
description: Caption for the file as rich text.
items:
$ref: '#/components/schemas/RichText'
required:
- type
Block:
type: object
description: A Block object represents a piece of content within a Notion page. Blocks are the building blocks of all page content and can be of many types including paragraphs, headings, lists, images, code, tables, and more. Blocks can contain other blocks as children, forming a tree structure.
properties:
object:
type: string
description: Always "block" for block objects.
const: block
id:
type: string
format: uuid
description: Unique identifier for the block.
parent:
$ref: '#/components/schemas/Parent'
type:
type: string
description: The type of block. Determines which type-specific content field is present. Common types include paragraph, heading_1, heading_2, heading_3, bulleted_list_item, numbered_list_item, to_do, toggle, code, image, divider, table, and many more.
enum:
- paragraph
- heading_1
- heading_2
- heading_3
- bulleted_list_item
- numbered_list_item
- to_do
- toggle
- child_page
- child_database
- embed
- image
- video
- file
- pdf
- bookmark
- callout
- quote
- equation
- divider
- table_of_contents
- column_list
- column
- link_preview
- synced_block
- template
- link_to_page
- table
- table_row
- code
- audio
- breadcrumb
created_time:
type: string
format: date-time
description: Date and time when the block was created (ISO 8601).
last_edited_time:
type: string
format: date-time
description: Date and time when the block was last edited (ISO 8601).
created_by:
$ref: '#/components/schemas/PartialUser'
last_edited_by:
$ref: '#/components/schemas/PartialUser'
archived:
type: boolean
description: Whether the block has been archived.
in_trash:
type: boolean
description: Whether the block is in the trash.
has_children:
type: boolean
description: Whether the block has child blocks nested within it.
additionalProperties: true
required:
- object
- id
- type
- created_time
- last_edited_time
- has_children
Page:
type: object
description: A Page object represents a page in a Notion workspace. Pages can exist as standalone pages in a workspace or as items within a database. Each page has properties, which are metadata fields defined by its parent database schema or by the page itself.
properties:
object:
type: string
description: Always "page" for page objects.
const: page
id:
type: string
format: uuid
description: Unique identifier for the page.
created_time:
type: string
format: date-time
description: Date and time when the page was created (ISO 8601).
last_edited_time:
type: string
format: date-time
description: Date and time when the page was last edited (ISO 8601).
created_by:
$ref: '#/components/schemas/PartialUser'
last_edited_by:
$ref: '#/components/schemas/PartialUser'
archived:
type: boolean
description: Whether the page has been archived (trashed).
in_trash:
type: boolean
description: Whether the page is in the trash.
icon:
description: Page icon, either an emoji or file.
oneOf:
- $ref: '#/components/schemas/Emoji'
- $ref: '#/components/schemas/File'
- type: 'null'
cover:
description: Page cover image.
oneOf:
- $ref: '#/components/schemas/File'
- type: 'null'
properties:
type: object
description: Property values of the page. Keys are property names or IDs.
additionalProperties: true
parent:
$ref: '#/components/schemas/Parent'
url:
type: string
format: uri
description: The URL of the page in Notion.
public_url:
type:
- string
- 'null'
format: uri
description: The public URL of the page, if the page has been published to the web. Otherwise null.
required:
- object
- id
- created_time
- last_edited_time
- created_by
- last_edited_by
- archived
- properties
- parent
- url
Parent:
type: object
description: A Parent object represents the parent of a page, database, or block. The parent can be a workspace, page, database, or block.
properties:
type:
type: string
description: The type of parent.
enum:
- database_id
- page_id
- block_id
- workspace
database_id:
type: string
format: uuid
description: The ID of the parent database. Present when type is "database_id".
page_id:
type: string
format: uuid
description: The ID of the parent page. Present when type is "page_id".
block_id:
type: string
format: uuid
description: The ID of the parent block. Present when type is "block_id".
workspace:
type: boolean
description: Always true when the parent is the workspace. Present when type is "workspace".
required:
- type
RichText:
type: object
description: A Rich Text object represents styled text content in Notion. Rich text can include annotations like bold, italic, and color, as well as links and mentions of other Notion objects.
properties:
type:
type: string
description: The type of this rich text object.
enum:
- text
- mention
- equation
text:
type: object
description: Text content and optional link. Present when type is "text".
properties:
content:
type: string
description: The actual text content.
link:
type:
- object
- 'null'
description: Optional link within the text.
properties:
url:
type: string
format: uri
description: The URL the text links to.
mention:
type: object
description: Mention content. Present when type is "mention". Can reference users, pages, databases, dates, or link previews.
additionalProperties: true
equation:
type: object
description: Equation content in KaTeX format. Present when type is "equation".
properties:
expression:
type: string
description: The LaTeX equation expression.
annotations:
type: object
description: Styling annotations applied to the text.
properties:
bold:
type: boolean
description: Whether the text is bold.
italic:
type: boolean
description: Whether the text is italic.
strikethrough:
type: boolean
description: Whether the text has a strikethrough.
underline:
type: boolean
description: Whether the text is underlined.
code:
type: boolean
description: Whether the text is formatted as inline code.
color:
type: string
description: The color of the text. Possible values include default, gray, brown, orange, yellow, green, blue, purple, pink, red, and their background variants (e.g., gray_background).
plain_text:
type: string
description: The plain text content without annotations.
href:
type:
- string
- 'null'
format: uri
description: The URL of any link in the text, or null.
required:
- type
- plain_text
ExternalFile:
type: object
description: An external file reference.
properties:
type:
type: string
const: external
description: Always "external".
external:
type: object
required:
- url
properties:
url:
type: string
format: uri
description: The URL of the external file.
required:
- type
- external
PartialUser:
type: object
description: A partial User object containing only the object type and ID. Used in created_by and last_edited_by fields.
properties:
object:
type: string
description: Always "user".
const: user
id:
type: string
format: uuid
description: Unique identifier for the user.
required:
- object
- id
Error:
type: object
description: An error response from the Notion API.
properties:
object:
type: string
description: Always "error" for error responses.
const: error
status:
type: integer
description: The HTTP status code.
code:
type: string
description: A machine-readable error code. Common codes include invalid_json, invalid_request_url, invalid_request, validation_error, missing_version, unauthorized, restricted_resource, object_not_found, conflict_error, rate_limited, internal_server_error, service_unavailable, and database_connection_unavailable.
message:
type: string
description: A human-readable error message.
request_id:
type: string
description: A unique identifier for the failed request.
required:
- object
- status
- code
- message
parameters:
NotionVersion:
name: Notion-Version
in: header
required: true
description: The version of the Notion API to use. The current version is 2022-06-28. This header is required for all API requests.
schema:
type: string
default: '2022-06-28'
examples:
- '2022-06-28'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Notion API uses bearer token authentication. Obtain an integration token from https://www.notion.so/my-integrations. Pass the token in the Authorization header as "Bearer {token}".