Notion
Notion — public JSON route
🔧 Developer ToolsON SCHEDULE
AUTH OAUTHCORS ✗AGENT ?HTTPS ✓COMMERCIAL ?
Notion listed as OAuth but exposes a keyless read route we verified (Documents & Productivity). Check docs for auth on write routes.
ON PROBE SCHEDULE
We probe without your API key. A 401/403 auth wall means the server is up — not a full health pass. Open provider docs ↗
Uptime historystarts after first probe
On our probe schedule. Uptime charts appear after the first check lands.
Example responsefrom provider docs — not verified by us
GET https://developers.notion.com/openapi.json
{
"openapi": "3.1.0",
"info": {
"title": "Notion API",
"version": "1.0.0",
"termsOfService": "https://notion.notion.site/Terms-and-Privacy-28ffdd083dc3473e9c2da6ec011b58ac"
},
"servers": [
{
"url": "https://api.notion.com"
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "Databases",
"description": "Database endpoints"
},
{
"name": "Data sources",
"description": "Data source endpoints"
}
],
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer"
},
"basicAuth": {
"type": "http",
"scheme": "basic"
}
},
"schemas": {
"agentIdParentForBlockBasedObjectResponse": {
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "agent_id",
"description": "The parent type."
},
"agent_id": {
"$ref": "#/components/schemas/idResponse",
"description": "The ID of the parent agent."
}
},
"additionalProperties": false,
"required": [
"type",
"agent_id"
]
},
"annotationRequest": {
"type": "object",
"properties": {
"bold": {
"type": "boolean",
"description": "Whether the text is formatted as bold."
},
"italic": {
"type": "boolean",
"description": "Whether the text is formatted as italic."
},
"strikethrough": {
"type": "boolean",
"description": "Whether the text is formatted with a strikethrough."
},
"underline": {
"type": "boolean",
"description": "Whether the text is formatted with an underline."
},
"code": {
"type": "boolean",
"description": "Whether the text is formatted as code."
},
"color": {
"$ref": "#/components/schemas/apiColor",
"description": "The color of the text."
}
}
},
"annotationResponse": {
"type": "object",
"properties": {
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"strikethrough": {
"type": "boolean"
},
"underline": {
"type": "boolean"
},
"code": {
"type": "boolean"
},
"color": {
"$ref": "#/components/schemas/apiColor"
}
},
"additionalProperties": false,
"required": [
"bold",
"italic"
]
},
"apiColor": {
"type": "string",
"enum": [
"default",
"gray"
],
"description": "One of: `default`, `gray`, `brown`, `orange`, `yellow`, `green`, `blue`, `purple`, `pink`, `red`, `default_background`, `gray_background`, `brown_background`, `orange_background`, `yellow_background`, `green_background`, `blue_background`, `purple_background`, `pink_background`, `red_background`"
},
"apiTranscriptionStatus": {
"type": "string",
"enum": [
"transcription_not_started",
"transcription_paused"
]
},
"arrayBasedPropertyValueResponse": {
"oneOf": [
{
"$ref": "#/components/schemas/titleArrayBasedPropertyValueResponse"
},
{
"$ref": "#/components/schemas/richTextArrayBasedPropertyValueResponse"
}
]
},
"arrayPartialRollupValueResponse": {
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "array",
"description": "Always `array`"
},
"array": {
"type": "array",
"items": {
"$ref": "#/components/schemas/simpleOrArrayPropertyValueResponse"
},
"maxItems": 100
}
},
"required": [
"type",
"array"
],
"title": "Array"
},
"asyncTaskMcpOperationName": {
"type": "string",
"enum": [
"create_pages",
"update_page"
]
}
},
"parameters": {
"notionVersion": {
"name": "Notion-Version",
"in": "header",
"required": true,
"schema": {
"enum": [
"2026-03-11"
]
},
"description": "The [API version](/reference/versioning) to use for this request. The latest version is `2026-03-11`."
}
}
},
"paths": {
"/v1/users/me": {
"get": {
"summary": "Retrieve your token's bot user",
"operationId": "get-self",
"tags": [
"Users"
],
"x-codeSamples": [
{
"lang": "javascript",
"label": "TypeScript SDK",
"source": "import { Client } from \"@notionhq/client\"\n\nconst notion = new Client({ auth: process.env.NOTION_API_KEY })\n\nconst response = await notion.users.me()"
}
],
"x-notion-docs-ref": "https://developers.notion.com/reference/get-self",
"x-notion-docs-guides": [
"https://developers.notion.com/guides/get-started/overview"
],
"parameters": [
{
"$ref": "#/components/parameters/notionVersion"
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/userObjectResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_400"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_401"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_403"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_404"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_409"
}
}
}
},
"429": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_429"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_500"
}
}
}
}
}
}
},
"/v1/users/{user_id}": {
"get": {
"summary": "Retrieve a user",
"operationId": "get-user",
"tags": [
"Users"
],
"x-codeSamples": [
{
"lang": "javascript",
"label": "TypeScript SDK",
"source": "import { Client } from \"@notionhq/client\"\n\nconst notion = new Client({ auth: process.env.NOTION_API_KEY })\n\nconst response = await notion.users.retrieve({\n user_id: \"e79a0b74-3aba-4149-9f74-0bb5791a6ee6\"\n})"
}
],
"x-notion-docs-ref": "https://developers.notion.com/reference/get-user",
"x-notion-docs-guides": [
"https://developers.notion.com/guides/get-started/overview"
],
"parameters": [
{
"name": "user_id",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/idRequest"
}
},
{
"$ref": "#/components/parameters/notionVersion"
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/userObjectResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_400"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_401"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_403"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_404"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_409"
}
}
}
},
"429": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_429"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_500"
}
}
}
}
}
}
},
"/v1/users": {
"get": {
"summary": "List all users",
"operationId": "get-users",
"tags": [
"Users"
],
"x-codeSamples": [
{
"lang": "javascript",
"label": "TypeScript SDK",
"source": "import { Client } from \"@notionhq/client\"\n\nconst notion = new Client({ auth: process.env.NOTION_API_KEY })\n\nconst response = await notion.users.list({\n start_cursor: undefined,\n page_size: 10\n})"
}
],
"x-notion-docs-ref": "https://developers.notion.com/reference/get-users",
"x-notion-docs-guides": [
"https://developers.notion.com/guides/get-started/overview"
],
"parameters": [
{
"name": "start_cursor",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "page_size",
"in": "query",
"schema": {
"type": "number"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"title": "User",
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "user"
},
"user": {
"$ref": "#/components/schemas/emptyObject"
},
"object": {
"type": "string",
"const": "list"
},
"next_cursor": {
"type": [
"string",
"null"
]
},
"has_more": {
"type": "boolean"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/userObjectResponse"
}
}
},
"required": [
"type",
"user"
]
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_400"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_401"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_403"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_404"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_409"
}
}
}
},
"429": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_429"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_500"
}
}
}
}
}
}
},
"/v1/pages": {
"post": {
"summary": "Create a page",
"operationId": "post-page",
"tags": [
"Pages"
],
"x-codeSamples": [
{
"lang": "javascript",
"label": "TypeScript SDK",
"source": "import { Client } from \"@notionhq/client\"\n\nconst notion = new Client({ auth: process.env.NOTION_API_KEY })\n\nconst response = await notion.pages.create({\n parent: {\n data_source_id: \"d9824bdc-8445-4327-be8b-5b47500af6ce\"\n },\n properties: {\n Name: {\n title: [{ text: { content: \"New Page Title\" } }]\n }\n }\n})"
}
],
"x-notion-docs-ref": "https://developers.notion.com/reference/post-page",
"x-notion-docs-guides": [
"https://developers.notion.com/guides/data-apis/working-with-page-content",
"https://developers.notion.com/guides/data-apis/creating-pages-from-templates"
],
"parameters": [
{
"$ref": "#/components/parameters/notionVersion"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"parent": {
"anyOf": [
{
"title": "Page Id",
"type": "object",
"properties": {
"page_id": {
"$ref": "#/components/schemas/idRequest"
},
"type": {
"type": "string",
"const": "page_id"
}
},
"additionalProperties": false,
"required": [
"page_id"
]
},
{
"title": "Database Id",
"type": "object",
"properties": {
"database_id": {
"$ref": "#/components/schemas/idRequest"
},
"type": {
"type": "string",
"const": "database_id"
}
},
"additionalProperties": false,
"required": [
"database_id"
]
}
]
},
"properties": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"title": "Title",
"type": "object",
"properties": {
"title": {
"type": "array",
"items": {
"$ref": "#/components/schemas/richTextItemRequest"
},
"maxItems": 100
},
"type": {
"type": "string",
"const": "title"
}
},
"additionalProperties": false,
"required": [
"title"
]
},
{
"title": "Rich Text",
"type": "object",
"properties": {
"rich_text": {
"type": "array",
"items": {
"$ref": "#/components/schemas/richTextItemRequest"
},
"maxItems": 100
},
"type": {
"type": "string",
"const": "rich_text"
}
},
"additionalProperties": false,
"required": [
"rich_text"
]
}
]
}
},
"icon": {
"anyOf": [
{
"$ref": "#/components/schemas/pageIconRequest"
},
{
"type": "null"
}
]
},
"cover": {
"anyOf": [
{
"$ref": "#/components/schemas/pageCoverRequest"
},
{
"type": "null"
}
]
},
"content": {
"type": "array",
"items": {
"$ref": "#/components/schemas/blockObjectRequest"
},
"maxItems": 100
},
"children": {
"type": "array",
"items": {
"$ref": "#/components/schemas/blockObjectRequest"
},
"maxItems": 100
},
"markdown": {
"description": "Page content as Notion-flavored Markdown. Mutually exclusive with content/children.",
"type": "string"
},
"allow_async": {
"description": "Set to true to receive an async_task response for markdown page creation. Only supported when markdown is provided.",
"type": "boolean"
}
},
"additionalProperties": false
}
}
}
}
}
},
"/v1/pages/{page_id}": {
"get": {
"summary": "Retrieve a page",
"operationId": "retrieve-a-page",
"tags": [
"Pages"
],
"x-codeSamples": [
{
"lang": "javascript",
"label": "TypeScript SDK",
"source": "import { Client } from \"@notionhq/client\"\n\nconst notion = new Client({ auth: process.env.NOTION_API_KEY })\n\nconst response = await notion.pages.retrieve({\n page_id: \"b55c9c91-384d-452b-81db-d1ef79372b75\"\n})"
}
],
"x-notion-docs-ref": "https://developers.notion.com/reference/retrieve-a-page",
"x-notion-docs-guides": [
"https://developers.notion.com/guides/data-apis/working-with-page-content"
],
"parameters": [
{
"name": "page_id",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/idRequest",
"description": "The ID of the page to retrieve."
}
},
{
"name": "filter_properties",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 100,
"description": "Supply a list of property IDs to filter properties in the response. Note that if a page doesn't have a property, it won't be included in the filtered response."
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/partialPageObjectResponse"
},
{
"$ref": "#/components/schemas/pageObjectResponse"
}
]
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_400"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_401"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_403"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_404"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_409"
}
}
}
},
"429": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_429"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_500"
}
}
}
}
}
},
"patch": {
"summary": "Update page",
"operationId": "patch-page",
"tags": [
"Pages"
],
"x-codeSamples": [
{
"lang": "javascript",
"label": "TypeScript SDK",
"source": "import { Client } from \"@notionhq/client\"\n\nconst notion = new Client({ auth: process.env.NOTION_API_KEY })\n\nconst response = await notion.pages.update({\n page_id: \"b55c9c91-384d-452b-81db-d1ef79372b75\",\n properties: {\n Name: {\n title: [{ text: { content: \"Updated Title\" } }]\n }\n }\n})"
}
],
"x-notion-docs-ref": "https://developers.notion.com/reference/patch-page",
"x-notion-docs-guides": [
"https://developers.notion.com/guides/data-apis/working-with-page-content"
],
"parameters": [
{
"name": "page_id",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/idRequest"
}
},
{
"$ref": "#/components/parameters/notionVersion"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"properties": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"title": "Title",
"type": "object",
"properties": {
"title": {
"type": "array",
"items": {
"$ref": "#/components/schemas/richTextItemRequest"
},
"maxItems": 100
},
"type": {
"type": "string",
"const": "title"
}
},
"additionalProperties": false,
"required": [
"title"
]
},
{
"title": "Rich Text",
"type": "object",
"properties": {
"rich_text": {
"type": "array",
"items": {
"$ref": "#/components/schemas/richTextItemRequest"
},
"maxItems": 100
},
"type": {
"type": "string",
"const": "rich_text"
}
},
"additionalProperties": false,
"required": [
"rich_text"
]
}
]
}
},
"icon": {
"anyOf": [
{
"$ref": "#/components/schemas/pageIconRequest"
},
{
"type": "null"
}
]
},
"cover": {
"anyOf": [
{
"$ref": "#/components/schemas/pageCoverRequest"
},
{
"type": "null"
}
]
},
"is_locked": {
"description": "Whether the page should be locked from editing in the Notion app UI. If not provided, the locked state will not be updated.",
"type": "boolean"
},
"template": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "default"
},
"timezone": {
"$ref": "#/components/schemas/templateTimezone"
}
},
"required": [
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "template_id"
},
"template_id": {
"$ref": "#/components/schemas/idRequest"
},
"timezone": {
"$ref": "#/components/schemas/templateTimezone"
}
},
"required": [
"type",
"template_id"
]
}
]
},
"erase_content": {
"description": "Whether to erase all existing content from the page. When used with a template, the template content replaces the existing content. When used without a template, simply clears the page content.",
"type": "boolean"
},
"in_trash": {
"type": "boolean"
},
"is_archived": {
"type": "boolean"
}
},
"additionalProperties": false
}
}
}
}
}
},
"/v1/pages/{page_id}/move": {
"post": {
"summary": "Move a page",
"operationId": "move-page",
"tags": [
"Pages"
],
"x-codeSamples": [
{
"lang": "javascript",
"label": "TypeScript SDK",
"source": "import { Client } from \"@notionhq/client\"\n\nconst notion = new Client({ auth: process.env.NOTION_API_KEY })\n\nconst response = await notion.pages.move({\n page_id: \"b55c9c91-384d-452b-81db-d1ef79372b75\",\n parent: {\n page_id: \"3c357473-a281-49a4-88c0-10d2b245a589\"\n }\n})"
}
],
"x-notion-docs-ref": "https://developers.notion.com/reference/move-page",
"x-notion-docs-guides": [
"https://developers.notion.com/guides/data-apis/working-with-page-content"
],
"parameters": [
{
"name": "page_id",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/idRequest",
"description": "The ID of the page to move."
}
},
{
"$ref": "#/components/parameters/notionVersion"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"parent": {
"oneOf": [
{
"type": "object",
"properties": {
"page_id": {
"$ref": "#/components/schemas/idRequest",
"description": "The ID of the parent page (with or without dashes), for example, 195de9221179449fab8075a27c979105"
},
"type": {
"type": "string",
"const": "page_id",
"description": "Always `page_id`"
}
},
"required": [
"page_id"
]
},
{
"type": "object",
"properties": {
"data_source_id": {
"$ref": "#/components/schemas/idRequest",
"description": "The ID of the parent data source (collection), with or without dashes. For example, f336d0bc-b841-465b-8045-024475c079dd"
},
"type": {
"type": "string",
"const": "data_source_id",
"description": "Always `data_source_id`"
}
},
"required": [
"data_source_id"
]
}
],
"description": "The new parent of the page."
}
},
"required": [
"parent"
]
}
}
}
}
}
},
"/v1/pages/{page_id}/properties/{property_id}": {
"get": {
"summary": "Retrieve a page property item",
"operationId": "retrieve-a-page-property",
"tags": [
"Pages"
],
"x-codeSamples": [
{
"lang": "javascript",
"label": "TypeScript SDK",
"source": "import { Client } from \"@notionhq/client\"\n\nconst notion = new Client({ auth: process.env.NOTION_API_KEY })\n\nconst response = await notion.pages.properties.retrieve({\n page_id: \"b55c9c91-384d-452b-81db-d1ef79372b75\",\n property_id: \"aBcD\"\n})"
}
],
"x-notion-docs-ref": "https://developers.notion.com/reference/retrieve-a-page-property",
"x-notion-docs-guides": [
"https://developers.notion.com/guides/data-apis/working-with-page-content"
],
"parameters": [
{
"name": "page_id",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/idRequest"
}
},
{
"name": "property_id",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/propertyItemObjectResponse"
},
{
"$ref": "#/components/schemas/propertyItemListResponse"
}
]
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_400"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_401"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_403"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_404"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_409"
}
}
}
},
"429": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_429"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_500"
}
}
}
}
}
}
},
"/v1/pages/{page_id}/markdown": {
"get": {
"summary": "Retrieve a page as markdown",
"operationId": "retrieve-page-markdown",
"tags": [
"Pages"
],
"x-codeSamples": [
{
"lang": "javascript",
"label": "TypeScript SDK",
"source": "import { Client } from \"@notionhq/client\"\n\nconst notion = new Client({ auth: process.env.NOTION_API_KEY })\n\nconst response = await notion.pages.retrieveMarkdown({\n page_id: \"b55c9c91-384d-452b-81db-d1ef79372b75\"\n})\n\nconsole.log(response.markdown)"
}
],
"x-notion-docs-ref": "https://developers.notion.com/reference/retrieve-page-markdown",
"x-notion-docs-guides": [
"https://developers.notion.com/guides/data-apis/working-with-markdown-content"
],
"parameters": [
{
"name": "page_id",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/idRequest",
"description": "The ID of the page (or block) to retrieve as markdown. Non-navigable block IDs from truncated responses can be passed here to fetch their subtrees."
}
},
{
"name": "include_transcript",
"in": "query",
"schema": {
"type": "boolean",
"description": "Whether to include meeting note transcripts. Defaults to false. When true, full transcripts are included; when false, a placeholder with the meeting note URL is shown instead."
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/pageMarkdownResponse"
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_400"
}
}
}
},
"401": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_401"
}
}
}
},
"403": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_403"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_404"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_409"
}
}
}
},
"429": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_429"
}
}
}
},
"500": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/error_api_500"
}
}
}
}
}
},
"patch": {
"summary": "Update a page's content as markdown",
"operationId": "update-page-markdown",
"tags": [
"Pages"
],
"x-codeSamples": [
{
"lang": "javascript",
"label": "TypeScript SDK",
"source": "import { Client } from \"@notionhq/client\"\n\nconst notion = new Client({ auth: process.env.NOTION_API_KEY })\n\nconst response = await notion.pages.updateMarkdown({\n page_id: \"b55c9c91-384d-452b-81db-d1ef79372b75\",\n type: \"update_content\",\n update_content: {\n content_updates: [\n {\n old_str: \"existing text to find\",\n new_str: \"replacement text\"\n }\n ]\n }\n})"
}
],
"x-notion-docs-ref": "https://developers.notion.com/reference/update-page-markdown",
"x-notion-docs-guides": [
"https://developers.notion.com/guides/data-apis/working-with-markdown-content"
],
"parameters": [
{
"name": "page_id",
"in": "path",
"required": true,
"schema": {
"$ref": "#/components/schemas/idRequest",
"description": "The ID of the page to update."
}
},
{
"$ref": "#/components/parameters/notionVersion"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"properties": {
"allow_async": {
"type": "boolean",
"description": "Set to true to opt into receiving an async_task result when this update operation is accepted for background execution. If omitted or false, the endpoint keeps the existing synchronous response shape."
}
}
},
{
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "insert_content",
"description": "Always `insert_content`"
},
"insert_content": {
"type": "object",
"properties": {
"content": {
"type": "string",
"examples": [
"## New Section\n\nInserted content here."
],
"description": "The enhanced markdown content to insert into the page."
},
"after": {
"type": "string",
"description": "Selection of existing content to insert after, using the ellipsis format (\"start text...end text\"). Omit to append at the end of the page."
},
"position": {
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "start",
"description": "Insert the content at the start of the page."
}
},
"required": [
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "end",
"description": "Insert the content at the end of the page."
}
},
"required": [
"type"
]
}
],
"description": "Explicit position for inserted content. Use {\"type\":\"start\"} to prepend or {\"type\":\"end\"} to append. Cannot be combined with after."
}
},
"required": [
"content"
],
"description": "Insert new content into the page."
}
},
"required": [
"type",
"insert_content"
],
"title": "Insert Content",
"deprecated": true
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "replace_content_range",
"description": "Always `replace_content_range`"
},
"replace_content_range": {
"type": "object",
"properties": {
"content": {
"type": "string",
"examples": [
"## Updated Section\n\nNew content replaces the old."
],
"description": "The new enhanced markdown content to replace the matched range."
},
"content_range": {
"type": "string",
"description": "Selection of existing content to replace, using the ellipsis format (\"start text...end text\")."
},
"allow_deleting_content": {
"type": "boolean",
"description": "Set to true to allow the operation to delete child pages or databases. Defaults to false."
}
},
"required": [
"content",
"content_range"
],
"description": "Replace a range of content in the page."
}
},
"required": [
"type",
"replace_content_range"
],
"title": "Replace Content Range",
"deprecated": true
}
]
}
]
}
}
}
}
}
}
},
"webhooks": {
"commentCreated": {
"post": {
"summary": "Comment created",
"description": "Webhook event for comment created in a workspace",
"operationId": "webhook-comment-created",
"tags": [
"Comment webhooks"
],
"security": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/commentCreatedWebhookPayload"
}
}
}
},
"responses": {
"200": {
"description": "Return an HTTP 200 status code to indicate that the data was received successfully."
}
}
}
},
"commentDeleted": {
"post": {
"summary": "Comment deleted",
"description": "Webhook event for comment deleted in a workspace",
"operationId": "webhook-comment-deleted",
"tags": [
"Comment webhooks"
],
"security": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/commentDeletedWebhookPayload"
}
}
}
},
"responses": {
"200": {
"description": "Return an HTTP 200 status code to indicate that the data was received successfully."
}
}
}
},
"commentUpdated": {
"post": {
"summary": "Comment updated",
"description": "Webhook event for comment updated in a workspace",
"operationId": "webhook-comment-updated",
"tags": [
"Comment webhooks"
],
"security": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/commentUpdatedWebhookPayload"
}
}
}
},
"responses": {
"200": {
"description": "Return an HTTP 200 status code to indicate that the data was received successfully."
}
}
}
},
"dataSourceContentUpdated": {
"post": {
"summary": "Data source content updated",
"description": "Webhook event for data source content updated in a workspace",
"operationId": "webhook-data-source-content-updated",
"tags": [
"Data source webhooks"
],
"security": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/dataSourceContentUpdatedWebhookPayload"
}
}
}
},
"responses": {
"200": {
"description": "Return an HTTP 200 status code to indicate that the data was received successfully."
}
}
}
},
"dataSourceCreated": {
"post": {
"summary": "Data source created",
"description": "Webhook event for data source created in a workspace",
"operationId": "webhook-data-source-created",
"tags": [
"Data source webhooks"
],
"security": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/dataSourceCreatedWebhookPayload"
}
}
}
},
"responses": {
"200": {
"description": "Return an HTTP 200 status code to indicate that the data was received successfully."
}
}
}
},
"dataSourceDeleted": {
"post": {
"summary": "Data source deleted",
"description": "Webhook event for data source deleted in a workspace",
"operationId": "webhook-data-source-deleted",
"tags": [
"Data source webhooks"
],
"security": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/dataSourceDeletedWebhookPayload"
}
}
}
},
"responses": {
"200": {
"description": "Return an HTTP 200 status code to indicate that the data was received successfully."
}
}
}
},
"dataSourceMoved": {
"post": {
"summary": "Data source moved",
"description": "Webhook event for data source moved in a workspace",
"operationId": "webhook-data-source-moved",
"tags": [
"Data source webhooks"
],
"security": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/dataSourceMovedWebhookPayload"
}
}
}
},
"responses": {
"200": {
"description": "Return an HTTP 200 status code to indicate that the data was received successfully."
}
}
}
},
"dataSourceSchemaUpdated": {
"post": {
"summary": "Data source schema updated",
"description": "Webhook event for data source schema updated in a workspace",
"operationId": "webhook-data-source-schema-updated",
"tags": [
"Data source webhooks"
],
"security": [],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/dataSourceSchemaUpdatedWebhookPayload"
}
}
}
},
"responses": {
"200": {
"description": "Return an HTTP 200 status code to indicate that the data was received successfully."
}
}
}
}
}
}Call itcurl · fetch · python
curl "https://developers.notion.com/openapi.json"const res = await fetch("https://developers.notion.com/openapi.json");
const data = await res.json();
console.log(data);import requests
res = requests.get("https://developers.notion.com/openapi.json")
print(res.json())BROWSER CALLS BLOCKED (NO CORS/HTTPS) — USE THE CURL SNIPPET
On schedule — auth-wall reachability checks pending
GET
/openapi.jsonPROBEDNotion — public JSON route
GET
/openapi.json?limit=5Paginated variant with limit parameter.
GET
/v1/users/meRetrieve your token's bot user
GET
/v1/users/{user_id}Retrieve a user
GET
/v1/usersList all users
GET
/v1/pages/{page_id}Retrieve a page
Machine-readable spec
We probe without your API key. A 401/403 auth wall means the server is up — not a full health pass. Export includes every documented route below.
Response-shape history
Not tracked yet. Shape-change history starts once this API joins our probe schedule.
Notion: common questions
Is Notion free to use?
Yes — Notion is a free developer tools API. Free tier: OAuth — some read routes may be public. Whether the free tier allows commercial use is unclear — check the provider docs.
Does Notion need an API key?
Yes — Notion authenticates with OAuth. See the provider docs for scopes and token setup; rate limits: Unpublished.
Can I call Notion from the browser?
Not directly — Notion doesn't send browser-friendly CORS headers, so call it from a server or proxy instead. Copy the curl or Python snippet on this page to get started.
Is Notion up right now?
Notion is catalogued but not yet on our probe schedule, so we don't publish a live status for it. Check the provider's own status page or docs for its current state.