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}".