openapi: 3.1.0
info:
  title: Notion 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: Blocks
    description: >-
      Blocks are the fundamental units of content in Notion. Every page is
      composed of blocks, which can be paragraphs, headings, images, tables,
      lists, and many other types. Blocks can have children, forming a tree
      structure. Use these endpoints to retrieve, update, delete blocks and
      manage block children.
    externalDocs:
      url: https://developers.notion.com/reference/block
  - name: Comments
    description: >-
      Comments allow integrations to read and create comments on pages and
      blocks within Notion. Comments support rich text content and are
      associated with discussion threads.
    externalDocs:
      url: https://developers.notion.com/reference/comment-object
  - 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
  - name: Pages
    description: >-
      Pages represent documents in Notion workspaces. They can exist as
      standalone pages or as entries within a database. Pages contain properties
      (metadata) and content composed of blocks. Use these endpoints to create,
      retrieve, update, archive, and manage page properties and content.
    externalDocs:
      url: https://developers.notion.com/reference/page
  - name: Search
    description: >-
      Search allows querying across all pages and databases that the integration
      has access to. Results can be filtered by object type and sorted by
      relevance or last edited time.
    externalDocs:
      url: https://developers.notion.com/reference/post-search
  - name: Users
    description: >-
      Users represent people or bots in a Notion workspace. Person users are
      human members of the workspace, while bot users represent API
      integrations. Use these endpoints to list users, retrieve specific users,
      or get information about the current bot integration.
    externalDocs:
      url: https://developers.notion.com/reference/user
paths:
  /pages:
    post:
      operationId: createPage
      summary: Notion Create a page
      description: >-
        Creates a new page that is a child of an existing page or database. If
        the parent is a database, the property values of the new page must
        conform to the parent database's schema. The request body must include a
        parent and properties. Page content can optionally be provided as an
        array of block objects in the children field.
      tags:
        - Pages
      externalDocs:
        url: https://developers.notion.com/reference/post-page
      parameters:
        - $ref: '#/components/parameters/NotionVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - parent
                - properties
              properties:
                parent:
                  $ref: '#/components/schemas/Parent'
                properties:
                  type: object
                  description: >-
                    Property values for the new page. Keys are property names or
                    IDs. If the parent is a database, the values must conform to
                    the database schema.
                  additionalProperties: true
                children:
                  type: array
                  description: Page content as an array of block objects.
                  items:
                    $ref: '#/components/schemas/Block'
                icon:
                  description: Page icon, either an emoji or external URL.
                  oneOf:
                    - $ref: '#/components/schemas/Emoji'
                    - $ref: '#/components/schemas/ExternalFile'
                cover:
                  $ref: '#/components/schemas/ExternalFile'
                  description: Page cover image as an external URL.
      responses:
        '200':
          description: Page successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /pages/{page_id}:
    get:
      operationId: retrievePage
      summary: Notion Retrieve a page
      description: >-
        Retrieves a Page object using the ID specified in the path. Returns page
        properties but not page content (blocks). To retrieve page content, use
        the retrieve block children endpoint on the page ID.
      tags:
        - Pages
      externalDocs:
        url: https://developers.notion.com/reference/retrieve-a-page
      parameters:
        - $ref: '#/components/parameters/NotionVersion'
        - name: page_id
          in: path
          required: true
          description: The ID of the page to retrieve.
          schema:
            type: string
            format: uuid
        - name: filter_properties
          in: query
          required: false
          description: >-
            A list of page property value IDs to include in the response. If
            provided, only the specified properties will be returned.
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: Page successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    patch:
      operationId: updatePage
      summary: Notion Update page properties
      description: >-
        Updates the properties of a page. Only the properties specified in the
        request body will be updated. Properties that are not included will
        remain unchanged. Can also update the page icon, cover, and archived
        status.
      tags:
        - Pages
      externalDocs:
        url: https://developers.notion.com/reference/patch-page
      parameters:
        - $ref: '#/components/parameters/NotionVersion'
        - name: page_id
          in: path
          required: true
          description: The ID of the page to update.
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                properties:
                  type: object
                  description: Property values to update.
                  additionalProperties: true
                archived:
                  type: boolean
                  description: Set to true to archive (trash) the page.
                icon:
                  description: Page icon to set.
                  oneOf:
                    - $ref: '#/components/schemas/Emoji'
                    - $ref: '#/components/schemas/ExternalFile'
                    - type: 'null'
                cover:
                  oneOf:
                    - $ref: '#/components/schemas/ExternalFile'
                    - type: 'null'
                  description: Page cover image to set or remove.
      responses:
        '200':
          description: Page successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Page'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /pages/{page_id}/properties/{property_id}:
    get:
      operationId: retrievePageProperty
      summary: Notion Retrieve a page property item
      description: >-
        Retrieves a property item from a page. For paginated properties like
        rich text, relation, rollup, and people, this endpoint returns a
        paginated list. For all other property types, it returns a single
        property item.
      tags:
        - Pages
      externalDocs:
        url: https://developers.notion.com/reference/retrieve-a-page-property
      parameters:
        - $ref: '#/components/parameters/NotionVersion'
        - name: page_id
          in: path
          required: true
          description: The ID of the page.
          schema:
            type: string
            format: uuid
        - name: property_id
          in: path
          required: true
          description: The ID of the property to retrieve.
          schema:
            type: string
        - name: start_cursor
          in: query
          required: false
          description: >-
            Pagination cursor for paginated property types. If supplied,
            returns results starting after the cursor.
          schema:
            type: string
        - name: page_size
          in: query
          required: false
          description: Maximum number of property items to return (max 100).
          schema:
            type: integer
            maximum: 100
      responses:
        '200':
          description: Property item successfully retrieved.
          content:
            application/json:
              schema:
                type: object
                description: >-
                  A property item object or a paginated list of property items,
                  depending on the property type.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /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'
  /blocks/{block_id}:
    get:
      operationId: retrieveBlock
      summary: Notion Retrieve a block
      description: >-
        Retrieves a Block object using the ID specified in the path. If the
        block is a page, the page properties will be returned. The block's
        children are not included; use the retrieve block children endpoint
        to get them.
      tags:
        - Blocks
      externalDocs:
        url: https://developers.notion.com/reference/retrieve-a-block
      parameters:
        - $ref: '#/components/parameters/NotionVersion'
        - name: block_id
          in: path
          required: true
          description: The ID of the block to retrieve.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Block successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Block'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    patch:
      operationId: updateBlock
      summary: Notion Update a block
      description: >-
        Updates the content of a block. The fields that can be updated depend on
        the block type. Blocks can also be archived by setting the archived
        field to true.
      tags:
        - Blocks
      externalDocs:
        url: https://developers.notion.com/reference/update-a-block
      parameters:
        - $ref: '#/components/parameters/NotionVersion'
        - name: block_id
          in: path
          required: true
          description: The ID of the block to update.
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: >-
                Block type-specific content to update. Include the block type
                key with the fields to modify.
              properties:
                archived:
                  type: boolean
                  description: Set to true to archive the block.
              additionalProperties: true
      responses:
        '200':
          description: Block successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Block'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    delete:
      operationId: deleteBlock
      summary: Notion Delete a block
      description: >-
        Sets a Block object, including page blocks, to archived: true using the
        ID specified in the path. This is equivalent to trashing the block in
        the Notion UI. To restore an archived block, use the update block
        endpoint to set archived to false.
      tags:
        - Blocks
      externalDocs:
        url: https://developers.notion.com/reference/delete-a-block
      parameters:
        - $ref: '#/components/parameters/NotionVersion'
        - name: block_id
          in: path
          required: true
          description: The ID of the block to delete (archive).
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Block successfully deleted (archived).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Block'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /blocks/{block_id}/children:
    get:
      operationId: retrieveBlockChildren
      summary: Notion Retrieve block children
      description: >-
        Returns a paginated array of child block objects contained in the block
        using the ID specified. This is used to read page content by passing a
        page ID as the block_id. Responses include a maximum of 100 blocks per
        request and are returned in the order they appear in the parent block.
      tags:
        - Blocks
      externalDocs:
        url: https://developers.notion.com/reference/get-block-children
      parameters:
        - $ref: '#/components/parameters/NotionVersion'
        - name: block_id
          in: path
          required: true
          description: >-
            The ID of the block whose children to retrieve. This can be a page
            ID to retrieve page content.
          schema:
            type: string
            format: uuid
        - name: start_cursor
          in: query
          required: false
          description: Pagination cursor to continue fetching results.
          schema:
            type: string
        - name: page_size
          in: query
          required: false
          description: Maximum number of blocks to return (max 100).
          schema:
            type: integer
            maximum: 100
      responses:
        '200':
          description: Block children successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    patch:
      operationId: appendBlockChildren
      summary: Notion Append block children
      description: >-
        Creates and appends new children blocks to the parent block specified by
        block_id. Returns the updated parent block. Blocks can be appended to
        pages, or to other blocks that support children. The maximum number of
        blocks that can be appended in a single request is 100.
      tags:
        - Blocks
      externalDocs:
        url: https://developers.notion.com/reference/patch-block-children
      parameters:
        - $ref: '#/components/parameters/NotionVersion'
        - name: block_id
          in: path
          required: true
          description: >-
            The ID of the block to append children to. This can be a page ID to
            add content to a page.
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - children
              properties:
                children:
                  type: array
                  description: >-
                    Array of block objects to append as children. Maximum 100
                    blocks per request.
                  items:
                    $ref: '#/components/schemas/Block'
                  maxItems: 100
                after:
                  type: string
                  format: uuid
                  description: >-
                    The ID of an existing block to insert the new children
                    after. If omitted, blocks are appended to the end.
      responses:
        '200':
          description: Block children successfully appended.
          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'
  /users:
    get:
      operationId: listUsers
      summary: Notion List all users
      description: >-
        Returns a paginated list of Users for the workspace. Guest users are
        not included. The response may include person users and bot users.
        Results are paginated with a maximum of 100 users per request.
      tags:
        - Users
      externalDocs:
        url: https://developers.notion.com/reference/get-users
      parameters:
        - $ref: '#/components/parameters/NotionVersion'
        - name: start_cursor
          in: query
          required: false
          description: Pagination cursor to continue fetching results.
          schema:
            type: string
        - name: page_size
          in: query
          required: false
          description: Maximum number of users to return (max 100).
          schema:
            type: integer
            maximum: 100
      responses:
        '200':
          description: Users successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /users/{user_id}:
    get:
      operationId: retrieveUser
      summary: Notion Retrieve a user
      description: >-
        Retrieves a User object using the ID specified in the path. Returns
        user details including name, avatar, and type (person or bot).
      tags:
        - Users
      externalDocs:
        url: https://developers.notion.com/reference/get-user
      parameters:
        - $ref: '#/components/parameters/NotionVersion'
        - name: user_id
          in: path
          required: true
          description: The ID of the user to retrieve.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: User successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /users/me:
    get:
      operationId: retrieveBotUser
      summary: Notion Retrieve the bot user
      description: >-
        Retrieves the bot User associated with the current API token. Returns
        information about the integration including its name, owner, and the
        workspace it belongs to.
      tags:
        - Users
      externalDocs:
        url: https://developers.notion.com/reference/get-self
      parameters:
        - $ref: '#/components/parameters/NotionVersion'
      responses:
        '200':
          description: Bot user successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /search:
    post:
      operationId: search
      summary: Notion Search by title
      description: >-
        Searches all parent or child pages and databases that have been shared
        with an integration. Returns results based on the query, filter, and
        sort parameters. Results are sorted by relevance by default but can be
        sorted by last_edited_time. The search indexing may not be immediate,
        so recently created or updated objects may not appear right away.
      tags:
        - Search
      externalDocs:
        url: https://developers.notion.com/reference/post-search
      parameters:
        - $ref: '#/components/parameters/NotionVersion'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  description: >-
                    The text to search for in page and database titles. If
                    omitted, returns all pages and databases.
                filter:
                  type: object
                  description: >-
                    Filter conditions. Currently only supports filtering by
                    object type (page or database).
                  properties:
                    value:
                      type: string
                      description: The type of object to filter by.
                      enum:
                        - page
                        - database
                    property:
                      type: string
                      description: Must be "object".
                      enum:
                        - object
                sort:
                  type: object
                  description: Sort conditions for the results.
                  properties:
                    direction:
                      type: string
                      description: The sort direction.
                      enum:
                        - ascending
                        - descending
                    timestamp:
                      type: string
                      description: The timestamp to sort by.
                      enum:
                        - last_edited_time
                start_cursor:
                  type: string
                  description: Pagination cursor to continue fetching results.
                page_size:
                  type: integer
                  description: Maximum number of results to return (max 100).
                  maximum: 100
                  default: 100
      responses:
        '200':
          description: Search results successfully returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /comments:
    get:
      operationId: listComments
      summary: Notion Retrieve comments
      description: >-
        Retrieves a list of unresolved comments from a page or block.
        Requires the integration to have read comment capabilities.
      tags:
        - Comments
      externalDocs:
        url: https://developers.notion.com/reference/list-comments
      parameters:
        - $ref: '#/components/parameters/NotionVersion'
        - name: block_id
          in: query
          required: true
          description: >-
            The ID of the block or page to retrieve comments for.
          schema:
            type: string
            format: uuid
        - name: start_cursor
          in: query
          required: false
          description: Pagination cursor to continue fetching results.
          schema:
            type: string
        - name: page_size
          in: query
          required: false
          description: Maximum number of comments to return (max 100).
          schema:
            type: integer
            maximum: 100
      responses:
        '200':
          description: Comments successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      operationId: createComment
      summary: Notion Create a comment
      description: >-
        Creates a comment on a page or in an existing discussion thread. The
        integration must have comment capabilities to use this endpoint.
      tags:
        - Comments
      externalDocs:
        url: https://developers.notion.com/reference/create-a-comment
      parameters:
        - $ref: '#/components/parameters/NotionVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - rich_text
              properties:
                parent:
                  type: object
                  description: >-
                    The parent page to create the comment on. Required if
                    discussion_id is not provided.
                  properties:
                    page_id:
                      type: string
                      format: uuid
                      description: The ID of the parent page.
                discussion_id:
                  type: string
                  format: uuid
                  description: >-
                    The ID of an existing discussion thread to add the comment
                    to. Required if parent is not provided.
                rich_text:
                  type: array
                  description: Rich text content of the comment.
                  items:
                    $ref: '#/components/schemas/RichText'
      responses:
        '200':
          description: Comment successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comment'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  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}".
  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'
  responses:
    BadRequest:
      description: The request was invalid or malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: The bearer token is missing, invalid, or the integration lacks access.
      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'
    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
  schemas:
    Page:
      type: object
      description: >-
        A Page object represents a page in a Notion workspace. Pages can exist
        as standalone pages in a workspace or as items within a database. Each
        page has properties, which are metadata fields defined by its parent
        database schema or by the page itself.
      properties:
        object:
          type: string
          description: Always "page" for page objects.
          const: page
        id:
          type: string
          format: uuid
          description: Unique identifier for the page.
        created_time:
          type: string
          format: date-time
          description: Date and time when the page was created (ISO 8601).
        last_edited_time:
          type: string
          format: date-time
          description: Date and time when the page was last edited (ISO 8601).
        created_by:
          $ref: '#/components/schemas/PartialUser'
        last_edited_by:
          $ref: '#/components/schemas/PartialUser'
        archived:
          type: boolean
          description: Whether the page has been archived (trashed).
        in_trash:
          type: boolean
          description: Whether the page is in the trash.
        icon:
          description: Page icon, either an emoji or file.
          oneOf:
            - $ref: '#/components/schemas/Emoji'
            - $ref: '#/components/schemas/File'
            - type: 'null'
        cover:
          description: Page cover image.
          oneOf:
            - $ref: '#/components/schemas/File'
            - type: 'null'
        properties:
          type: object
          description: >-
            Property values of the page. Keys are property names or IDs.
          additionalProperties: true
        parent:
          $ref: '#/components/schemas/Parent'
        url:
          type: string
          format: uri
          description: The URL of the page in Notion.
        public_url:
          type:
            - string
            - 'null'
          format: uri
          description: >-
            The public URL of the page, if the page has been published to the
            web. Otherwise null.
      required:
        - object
        - id
        - created_time
        - last_edited_time
        - created_by
        - last_edited_by
        - archived
        - properties
        - parent
        - url
    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
    Block:
      type: object
      description: >-
        A Block object represents a piece of content within a Notion page.
        Blocks are the building blocks of all page content and can be of many
        types including paragraphs, headings, lists, images, code, tables, and
        more. Blocks can contain other blocks as children, forming a tree
        structure.
      properties:
        object:
          type: string
          description: Always "block" for block objects.
          const: block
        id:
          type: string
          format: uuid
          description: Unique identifier for the block.
        parent:
          $ref: '#/components/schemas/Parent'
        type:
          type: string
          description: >-
            The type of block. Determines which type-specific content field is
            present. Common types include paragraph, heading_1, heading_2,
            heading_3, bulleted_list_item, numbered_list_item, to_do, toggle,
            code, image, divider, table, and many more.
          enum:
            - paragraph
            - heading_1
            - heading_2
            - heading_3
            - bulleted_list_item
            - numbered_list_item
            - to_do
            - toggle
            - child_page
            - child_database
            - embed
            - image
            - video
            - file
            - pdf
            - bookmark
            - callout
            - quote
            - equation
            - divider
            - table_of_contents
            - column_list
            - column
            - link_preview
            - synced_block
            - template
            - link_to_page
            - table
            - table_row
            - code
            - audio
            - breadcrumb
        created_time:
          type: string
          format: date-time
          description: Date and time when the block was created (ISO 8601).
        last_edited_time:
          type: string
          format: date-time
          description: Date and time when the block was last edited (ISO 8601).
        created_by:
          $ref: '#/components/schemas/PartialUser'
        last_edited_by:
          $ref: '#/components/schemas/PartialUser'
        archived:
          type: boolean
          description: Whether the block has been archived.
        in_trash:
          type: boolean
          description: Whether the block is in the trash.
        has_children:
          type: boolean
          description: Whether the block has child blocks nested within it.
      additionalProperties: true
      required:
        - object
        - id
        - type
        - created_time
        - last_edited_time
        - has_children
    User:
      type: object
      description: >-
        A User object represents a user in a Notion workspace. Users can be
        either people (human workspace members) or bots (API integrations).
        User objects include identifying information such as name, email, and
        avatar URL.
      properties:
        object:
          type: string
          description: Always "user" for user objects.
          const: user
        id:
          type: string
          format: uuid
          description: Unique identifier for the user.
        type:
          type: string
          description: >-
            The type of user. "person" for human workspace members, "bot" for
            API integrations.
          enum:
            - person
            - bot
        name:
          type:
            - string
            - 'null'
          description: Display name of the user.
        avatar_url:
          type:
            - string
            - 'null'
          format: uri
          description: URL of the user's avatar image.
        person:
          type: object
          description: >-
            Person-specific information. Only present when type is "person".
          properties:
            email:
              type: string
              format: email
              description: Email address of the person.
        bot:
          type: object
          description: >-
            Bot-specific information. Only present when type is "bot".
          properties:
            owner:
              type: object
              description: Information about the bot's owner.
              properties:
                type:
                  type: string
                  enum:
                    - workspace
                    - user
                workspace:
                  type: boolean
                  description: Whether the bot is owned by the workspace.
            workspace_name:
              type:
                - string
                - 'null'
              description: The name of the workspace the bot belongs to.
      required:
        - object
        - id
    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
    Comment:
      type: object
      description: >-
        A Comment object represents a comment on a Notion page or block.
        Comments contain rich text content and are associated with discussion
        threads.
      properties:
        object:
          type: string
          description: Always "comment" for comment objects.
          const: comment
        id:
          type: string
          format: uuid
          description: Unique identifier for the comment.
        parent:
          type: object
          description: The parent page or block the comment belongs to.
          properties:
            type:
              type: string
              enum:
                - page_id
                - block_id
            page_id:
              type: string
              format: uuid
            block_id:
              type: string
              format: uuid
        discussion_id:
          type: string
          format: uuid
          description: The ID of the discussion thread the comment belongs to.
        created_time:
          type: string
          format: date-time
          description: Date and time when the comment was created (ISO 8601).
        last_edited_time:
          type: string
          format: date-time
          description: Date and time when the comment was last edited (ISO 8601).
        created_by:
          $ref: '#/components/schemas/PartialUser'
        rich_text:
          type: array
          description: Rich text content of the comment.
          items:
            $ref: '#/components/schemas/RichText'
      required:
        - object
        - id
        - parent
        - discussion_id
        - created_time
        - last_edited_time
        - created_by
        - rich_text
    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
    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
    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
    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
    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
    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
    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