Documents & Productivity — entry 017 of 31

Notion

Verified Jul 2026

Notion's API lets integrations read and write pages, databases, blocks, and comments across a connected workspace, authenticated with an internal integration token or a public OAuth2 app for cross-workspace distribution. Every plan, including Notion's free tier, can create and use an internal integration at roughly 3 requests/second of throughput; higher volume means spreading calls across multiple integrations, not upgrading a plan. The live API host sends no CORS headers, so calls need to run server-side.

productivitydatabasecollaborationautomation

Visit developers.notion.com ↗Read the docs ↗Pricing ↗Status ↗More Documents & Productivity

AuthenticationOAuthRequires an OAuth flow; expect app registration.

HTTPSSupportedTraffic is encrypted in transit.

CORSDisabledBrowser calls need a server-side proxy.

PricingFreemiumA usable free tier exists, with paid plans for more volume.

FormatsJSONResponses can be requested as JSON.

GreatAPIs Score

Score74out of 100

Authentication8/25OAuth flow required

Pricing17/20Freemium tier available

Docs20/20Machine-readable spec file bundled

Formats9/15Single response format

Freshness20/20Verified within 6 months

Embed this badge

<a href="https://greatapis.com/api/notion/"><img src="https://greatapis.com/badge/notion.svg" alt="Scored 74 on greatapis.com"></a>

Auth quickstart

Register an app / run the OAuth flow to obtain a bearer token.
Send it as an Authorization headerAuthorization: Bearer <token>

Stored keyNo key stored

Your key is stored only in this browser (localStorage) and sent directly to the API — never to greatapis.

Endpoints

Servers

https://api.notion.com

Users1

GET/v1/users/{id}Retrieve a user

Parameters

Name	In	Required	Type
`id`	path	yes	string
`Notion-Version`	header	no	string

Request body

application/x-www-form-urlencoded

Responses

Status	Description	Schema
`200`	200 Success - Retrieve a user	—

Databases3

GET/v1/databases/{id}Retrieve a database

Parameters

Name	In	Required	Type
`id`	path	yes	string
`Notion-Version`	header	no	string

Responses

Status	Description	Schema
`200`	200 Success - Retrieve a Database	—

PATCH/v1/databases/{id}Update a database

Parameters

Name	In	Required	Type
`id`	path	yes	string
`Notion-Version`	header	no	string

Request body

application/json

Responses

Status	Description	Schema
`200`	200 Success - Update a Database	—

POST/v1/databases/{id}/queryQuery a database

Parameters

Name	In	Required	Type
`id`	path	yes	string
`Notion-Version`	header	no	string

Request body

application/json

Responses

Status	Description	Schema
`200`	200 Success - Query a Database (Single Filter)	—

Pages3

GET/v1/pages/{id}Retrieve a Page

Parameters

Name	In	Required	Type
`id`	path	yes	string
`Notion-Version`	header	no	string
	header	no	string

Responses

Status	Description	Schema
`200`	200 Success - Retrieve a Page	—

PATCH/v1/pages/{id}Update Page properties

Parameters

Name	In	Required	Type
`id`	path	yes	string
`Notion-Version`	header	no	string

Request body

application/json

Responses

Status	Description	Schema
`200`	200 Success - Update Page properties	—

GET/v1/pages/{page_id}/properties/{property_id}Retrieve a Page Property Item

Parameters

Name	In	Required	Type
`page_id`	path	yes	string
`property_id`	path	yes	string

Responses

Status	Description	Schema
`200`	200 Success - Retrieve a Page Property Item	—

Blocks5

GET/v1/blocks/{id}Retrieve a block

Parameters

Name	In	Required	Type
`id`	path	yes	string
`Notion-Version`	header	no	string

Responses

Status	Description	Schema
`200`	200 Success - Retrieve a block	—

PATCH/v1/blocks/{id}Update a block

Parameters

Name	In	Required	Type
`id`	path	yes	string
`Notion-Version`	header	no	string

Request body

application/json

Responses

Status	Description	Schema
`200`	200 Success - Update a block	—

DELETE/v1/blocks/{id}Delete a block

Parameters

Name	In	Required	Type
`id`	path	yes	string
`Notion-Version`	header	no	string

Responses

Status	Description	Schema
`200`	200 Success - Delete a block	—

GET/v1/blocks/{id}/childrenRetrieve block children

Parameters

Name	In	Required	Type
`id`	path	yes	string
`page_size`	query	no	string
`Notion-Version`	header	no	string

Responses

Status	Description	Schema
`200`	200 Success - Retrieve block children	—

PATCH/v1/blocks/{id}/childrenAppend block children

Parameters

Name	In	Required	Type
`id`	path	yes	string
`Notion-Version`	header	no	string

Request body

application/json

Responses

Status	Description	Schema
`200`	200 Success - Append block children	—

Comments1

GET/v1/commentsRetrieve comments

Parameters

Name	In	Required	Type
`block_id`	query	no	string
`page_size`	query	no	string
`Notion-Version`	header	no	string

Request body

application/x-www-form-urlencoded

Responses

Status	Description	Schema
`200`	200 Success - Retrieve a comment	—

Try it

Operation

API key

Developer reference

Base URLhttps://api.notion.com

Rate limit

Average of 3 requests/second per integration (bursts allowed); a separate per-workspace limit scaled to plan also applies. Exceeding either returns 429 rate_limited.

Key endpoints

POST/v1/databases/{id}/query
GET/v1/pages/{id}
PATCH/v1/pages/{id}
GET/v1/blocks/{id}/children
GET/v1/comments

SDKs

JavaScript ↗

GreatAPIs Score

Embed this badge

Auth quickstart

Endpoints

Try it

Developer reference

People comparing Notion also look at…

Vector Express v2.0

CloudConvert

Cloudmersive Document and Data Conversion

CraftMyPDF

Html2PDF

iLovePDF