openapi: 3.1.0
info:
title: Notion Blocks Databases 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: Databases
description: Databases are collections of Notion pages organized with a shared schema of properties. Each database defines columns (properties) that all its pages share. Databases support filtering, sorting, and querying. Use these endpoints to create, retrieve, update, and query databases.
externalDocs:
url: https://developers.notion.com/reference/database
paths:
/databases:
post:
operationId: createDatabase
summary: Notion Create a database
description: Creates a database as a subpage of the specified parent page, with the specified properties schema. A database can be created with a title, properties defining the schema, and an optional description. The parent must be a page that the integration has access to.
tags:
- Databases
externalDocs:
url: https://developers.notion.com/reference/create-a-database
parameters:
- $ref: '#/components/parameters/NotionVersion'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- parent
- properties
properties:
parent:
$ref: '#/components/schemas/Parent'
title:
type: array
description: Rich text array for the database title.
items:
$ref: '#/components/schemas/RichText'
description:
type: array
description: Rich text array for the database description.
items:
$ref: '#/components/schemas/RichText'
properties:
type: object
description: Schema of the database properties. Keys are property names, values are property schema objects defining the type and configuration.
additionalProperties:
$ref: '#/components/schemas/PropertySchema'
is_inline:
type: boolean
description: Whether the database appears inline within its parent page rather than as a full page.
icon:
description: Database icon.
oneOf:
- $ref: '#/components/schemas/Emoji'
- $ref: '#/components/schemas/ExternalFile'
cover:
$ref: '#/components/schemas/ExternalFile'
description: Database cover image.
responses:
'200':
description: Database successfully created.
content:
application/json:
schema:
$ref: '#/components/schemas/Database'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
/databases/{database_id}:
get:
operationId: retrieveDatabase
summary: Notion Retrieve a database
description: Retrieves a Database object using the ID specified in the path. Returns the database properties schema and metadata.
tags:
- Databases
externalDocs:
url: https://developers.notion.com/reference/retrieve-a-database
parameters:
- $ref: '#/components/parameters/NotionVersion'
- name: database_id
in: path
required: true
description: The ID of the database to retrieve.
schema:
type: string
format: uuid
responses:
'200':
description: Database successfully retrieved.
content:
application/json:
schema:
$ref: '#/components/schemas/Database'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
patch:
operationId: updateDatabase
summary: Notion Update a database
description: Updates an existing database's title, description, or properties schema. Only the fields specified in the request body will be updated. To remove a property from the schema, set its value to null.
tags:
- Databases
externalDocs:
url: https://developers.notion.com/reference/update-a-database
parameters:
- $ref: '#/components/parameters/NotionVersion'
- name: database_id
in: path
required: true
description: The ID of the database to update.
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
title:
type: array
description: Updated database title as rich text.
items:
$ref: '#/components/schemas/RichText'
description:
type: array
description: Updated database description as rich text.
items:
$ref: '#/components/schemas/RichText'
properties:
type: object
description: Updated property schema. Include only properties to add or modify. Set a property value to null to remove it.
additionalProperties: true
icon:
description: Updated database icon.
oneOf:
- $ref: '#/components/schemas/Emoji'
- $ref: '#/components/schemas/ExternalFile'
- type: 'null'
cover:
oneOf:
- $ref: '#/components/schemas/ExternalFile'
- type: 'null'
description: Updated database cover image.
is_inline:
type: boolean
description: Whether the database is inline.
responses:
'200':
description: Database successfully updated.
content:
application/json:
schema:
$ref: '#/components/schemas/Database'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
/databases/{database_id}/query:
post:
operationId: queryDatabase
summary: Notion Query a database
description: Gets a list of Pages and/or Databases contained in the database, filtered and ordered according to the filter and sort conditions specified in the request body. Responses are paginated and limited to 100 results per request.
tags:
- Databases
externalDocs:
url: https://developers.notion.com/reference/post-database-query
parameters:
- $ref: '#/components/parameters/NotionVersion'
- name: database_id
in: path
required: true
description: The ID of the database to query.
schema:
type: string
format: uuid
- name: filter_properties
in: query
required: false
description: A list of property IDs to include in the response. Only the specified properties will be returned for each page.
schema:
type: array
items:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
filter:
type: object
description: Filter conditions to apply. Supports compound filters using and/or as well as property-specific filters.
additionalProperties: true
sorts:
type: array
description: Sort conditions to order the results. Multiple sorts can be applied; they are processed in the order provided.
items:
type: object
properties:
property:
type: string
description: The name of the property to sort by.
timestamp:
type: string
description: The timestamp to sort by. Possible values are created_time or last_edited_time.
enum:
- created_time
- last_edited_time
direction:
type: string
description: The sort direction.
enum:
- ascending
- descending
start_cursor:
type: string
description: Pagination cursor from a previous response to continue fetching results.
page_size:
type: integer
description: Maximum number of results to return (max 100).
maximum: 100
default: 100
responses:
'200':
description: Database query results.
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedList'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
components:
schemas:
PaginatedList:
type: object
description: A paginated list of results returned by list and query endpoints. All paginated responses follow the same structure with a results array, pagination info, and object type.
properties:
object:
type: string
description: Always "list" for paginated responses.
const: list
results:
type: array
description: The array of result objects for the current page.
items:
type: object
additionalProperties: true
next_cursor:
type:
- string
- 'null'
description: The cursor to use for the next page of results, or null if there are no more results.
has_more:
type: boolean
description: Whether there are more results available beyond this page.
type:
type: string
description: The type of objects in the results array.
request_id:
type: string
description: A unique identifier for this API request.
required:
- object
- results
- next_cursor
- has_more
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
Database:
type: object
description: A Database object represents a database in Notion. Databases are collections of pages that share a common schema of properties. The schema defines the columns and their types that all pages in the database will have.
properties:
object:
type: string
description: Always "database" for database objects.
const: database
id:
type: string
format: uuid
description: Unique identifier for the database.
created_time:
type: string
format: date-time
description: Date and time when the database was created (ISO 8601).
last_edited_time:
type: string
format: date-time
description: Date and time when the database was last edited (ISO 8601).
created_by:
$ref: '#/components/schemas/PartialUser'
last_edited_by:
$ref: '#/components/schemas/PartialUser'
title:
type: array
description: Title of the database as rich text.
items:
$ref: '#/components/schemas/RichText'
description:
type: array
description: Description of the database as rich text.
items:
$ref: '#/components/schemas/RichText'
icon:
description: Database icon, either an emoji or file.
oneOf:
- $ref: '#/components/schemas/Emoji'
- $ref: '#/components/schemas/File'
- type: 'null'
cover:
description: Database cover image.
oneOf:
- $ref: '#/components/schemas/File'
- type: 'null'
properties:
type: object
description: Schema of database properties. Keys are property names, values are property schema objects defining the type and configuration of each column.
additionalProperties:
$ref: '#/components/schemas/PropertySchema'
parent:
$ref: '#/components/schemas/Parent'
url:
type: string
format: uri
description: The URL of the database in Notion.
public_url:
type:
- string
- 'null'
format: uri
description: The public URL of the database, if published to the web. Otherwise null.
archived:
type: boolean
description: Whether the database has been archived.
in_trash:
type: boolean
description: Whether the database is in the trash.
is_inline:
type: boolean
description: Whether the database is inline (appears within its parent page rather than as a full page).
required:
- object
- id
- created_time
- last_edited_time
- created_by
- last_edited_by
- title
- description
- properties
- parent
- url
- archived
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
PropertySchema:
type: object
description: A Property Schema object defines a database property's configuration including its type and type-specific settings. Common property types include title, rich_text, number, select, multi_select, date, people, files, checkbox, url, email, phone_number, formula, relation, rollup, created_time, created_by, last_edited_time, last_edited_by, and status.
properties:
id:
type: string
description: The ID of the property.
name:
type: string
description: The name of the property.
type:
type: string
description: The type of property.
enum:
- title
- rich_text
- number
- select
- multi_select
- date
- people
- files
- checkbox
- url
- email
- phone_number
- formula
- relation
- rollup
- created_time
- created_by
- last_edited_time
- last_edited_by
- status
- unique_id
- verification
additionalProperties: true
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
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
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
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'
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}".