Connections use the API to access Notion’s pages, databases, and users. Connections can connect services to Notion and build interactive experiences for users within Notion. Use the navigation on the left to find details for objects and endpoints used in the API.

Conventions

The base URL to send all API requests is https://api.notion.com. HTTPS is required for all API requests. The Notion API follows RESTful conventions when possible, with most operations performed via GET, POST, PATCH, and DELETE requests on page and database resources. Request and response bodies are encoded as JSON.

JSON conventions

Top-level resources have an "object" property. This property can be used to determine the type of the resource (e.g. "database", "user", etc.)
Top-level resources are addressable by a UUIDv4 "id" property. You may omit dashes from the ID when making requests to the API, e.g. when copying the ID from a Notion URL.
Property names are in snake_case (not camelCase or kebab-case).
Temporal values (dates and datetimes) are encoded in ISO 8601 strings. Datetimes will include the time value (2020-08-12T02:12:33.231Z) while dates will include only the date (2020-08-12)
The Notion API does not support empty strings. To unset a string value for properties like a url page property value, for example, use an explicit null instead of "".

Code samples & SDKs

Samples requests and responses are shown for each endpoint. Requests are shown using the Notion JavaScript SDK, and cURL. These samples make it easy to copy, paste, and modify as you build your connection. Notion SDKs are open source projects that you can install to easily start building. You may also choose any other language or library that allows you to make HTTP requests.

Endpoints that return lists of objects support cursor-based pagination requests. By default, Notion returns ten items per API call. If the number of items in a response from a support endpoint exceeds the default, then a connection can use pagination to request a specific set of the results and/or to limit the number of returned items.

Supported endpoints

HTTP method	Endpoint
GET	List all users
GET	List block children
GET	List comments
GET	Retrieve a page property item
GET	List file uploads
GET	List data source templates
GET	List views
GET	Get view query results
POST	Query a data source
POST	Create a view query
POST	Search

Responses

If an endpoint supports pagination, then the response object contains the below fields.

Field	Type	Description
`has_more`	`boolean`	Whether the response includes the end of the list. `false` if there are no more results. Otherwise, `true`.
`next_cursor`	`string`	A string that can be used to retrieve the next page of results by passing the value as the `start_cursor` parameter to the same endpoint. Only available when `has_more` is true.
`object`	`"list"`	The constant string `"list"`.
`results`	`array of objects`	The list, or partial list, of endpoint-specific results. Refer to a supported endpoint’s individual documentation for details.
`type`	`"block"` `"comment"` `"data_source"` `"file_upload"` `"page"` `"page_or_database"` `"property_item"` `"template"` `"user"` `"view"`	A constant string that represents the type of the objects in `results`.
`{type}`	`paginated list object`	An object containing type-specific pagination information. For `property_item`s, the value corresponds to the paginated page property type. For all other types, the value is an empty object.

Parameters for paginated requests

Parameter Type Description

Parameter	Type	Description
`page_size`	`number`	The number of items from the full list to include in the response. Default: `100` Maximum: `100` The response may contain fewer than the default number of results.
`start_cursor`	`string`	A `next_cursor` value returned in a previous response. Treat this as an opaque value. Defaults to `undefined`, which returns results from the beginning of the list.

page_size

number

The number of items from the full list to include in the response.

Default: 100
Maximum: 100

The response may contain fewer than the default number of results.

start_cursor

string

A next_cursor value returned in a previous response. Treat this as an opaque value.

Defaults to undefined, which returns results from the beginning of the list.