Notion API

naftiko: 1.0.0-alpha2
info:
  label: 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.
  tags:
  - Notion
  - API
  created: '2026-05-06'
  modified: '2026-05-06'
capability:
  consumes:
  - type: http
    namespace: notion
    baseUri: https://api.notion.com/v1
    description: Notion API HTTP API.
    authentication:
      type: bearer
      token: '{{NOTION_TOKEN}}'
    resources:
    - name: pages
      path: /pages
      operations:
      - name: createpage
        method: POST
        description: Notion Create a page
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: pages-page-id
      path: /pages/{page_id}
      operations:
      - name: retrievepage
        method: GET
        description: Notion Retrieve a page
        inputParameters:
        - name: page_id
          in: path
          type: string
          required: true
          description: The ID of the page to retrieve.
        - name: filter_properties
          in: query
          type: array
          description: A list of page property value IDs to include in the response. If provided, only the specified properties
            will be returned.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: updatepage
        method: PATCH
        description: Notion Update page properties
        inputParameters:
        - name: page_id
          in: path
          type: string
          required: true
          description: The ID of the page to update.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: pages-page-id-properties-property-id
      path: /pages/{page_id}/properties/{property_id}
      operations:
      - name: retrievepageproperty
        method: GET
        description: Notion Retrieve a page property item
        inputParameters:
        - name: page_id
          in: path
          type: string
          required: true
          description: The ID of the page.
        - name: property_id
          in: path
          type: string
          required: true
          description: The ID of the property to retrieve.
        - name: start_cursor
          in: query
          type: string
          description: Pagination cursor for paginated property types. If supplied, returns results starting after the cursor.
        - name: page_size
          in: query
          type: integer
          description: Maximum number of property items to return (max 100).
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: databases
      path: /databases
      operations:
      - name: createdatabase
        method: POST
        description: Notion Create a database
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: databases-database-id
      path: /databases/{database_id}
      operations:
      - name: retrievedatabase
        method: GET
        description: Notion Retrieve a database
        inputParameters:
        - name: database_id
          in: path
          type: string
          required: true
          description: The ID of the database to retrieve.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: updatedatabase
        method: PATCH
        description: Notion Update a database
        inputParameters:
        - name: database_id
          in: path
          type: string
          required: true
          description: The ID of the database to update.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: databases-database-id-query
      path: /databases/{database_id}/query
      operations:
      - name: querydatabase
        method: POST
        description: Notion Query a database
        inputParameters:
        - name: database_id
          in: path
          type: string
          required: true
          description: The ID of the database to query.
        - name: filter_properties
          in: query
          type: array
          description: A list of property IDs to include in the response. Only the specified properties will be returned for
            each page.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: blocks-block-id
      path: /blocks/{block_id}
      operations:
      - name: retrieveblock
        method: GET
        description: Notion Retrieve a block
        inputParameters:
        - name: block_id
          in: path
          type: string
          required: true
          description: The ID of the block to retrieve.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: updateblock
        method: PATCH
        description: Notion Update a block
        inputParameters:
        - name: block_id
          in: path
          type: string
          required: true
          description: The ID of the block to update.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: deleteblock
        method: DELETE
        description: Notion Delete a block
        inputParameters:
        - name: block_id
          in: path
          type: string
          required: true
          description: The ID of the block to delete (archive).
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: blocks-block-id-children
      path: /blocks/{block_id}/children
      operations:
      - name: retrieveblockchildren
        method: GET
        description: Notion Retrieve block children
        inputParameters:
        - name: block_id
          in: path
          type: string
          required: true
          description: The ID of the block whose children to retrieve. This can be a page ID to retrieve page content.
        - name: start_cursor
          in: query
          type: string
          description: Pagination cursor to continue fetching results.
        - name: page_size
          in: query
          type: integer
          description: Maximum number of blocks to return (max 100).
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: appendblockchildren
        method: PATCH
        description: Notion Append block children
        inputParameters:
        - name: block_id
          in: path
          type: string
          required: true
          description: The ID of the block to append children to. This can be a page ID to add content to a page.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: users
      path: /users
      operations:
      - name: listusers
        method: GET
        description: Notion List all users
        inputParameters:
        - name: start_cursor
          in: query
          type: string
          description: Pagination cursor to continue fetching results.
        - name: page_size
          in: query
          type: integer
          description: Maximum number of users to return (max 100).
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: users-user-id
      path: /users/{user_id}
      operations:
      - name: retrieveuser
        method: GET
        description: Notion Retrieve a user
        inputParameters:
        - name: user_id
          in: path
          type: string
          required: true
          description: The ID of the user to retrieve.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: users-me
      path: /users/me
      operations:
      - name: retrievebotuser
        method: GET
        description: Notion Retrieve the bot user
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: search
      path: /search
      operations:
      - name: search
        method: POST
        description: Notion Search by title
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: comments
      path: /comments
      operations:
      - name: listcomments
        method: GET
        description: Notion Retrieve comments
        inputParameters:
        - name: block_id
          in: query
          type: string
          required: true
          description: The ID of the block or page to retrieve comments for.
        - name: start_cursor
          in: query
          type: string
          description: Pagination cursor to continue fetching results.
        - name: page_size
          in: query
          type: integer
          description: Maximum number of comments to return (max 100).
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: createcomment
        method: POST
        description: Notion Create a comment
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: notion-rest
    description: REST adapter for Notion API.
    resources:
    - path: /pages
      name: createpage
      operations:
      - method: POST
        name: createpage
        description: Notion Create a page
        call: notion.createpage
        outputParameters:
        - type: object
          mapping: $.
    - path: /pages/{page_id}
      name: retrievepage
      operations:
      - method: GET
        name: retrievepage
        description: Notion Retrieve a page
        call: notion.retrievepage
        with:
          page_id: rest.page_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /pages/{page_id}
      name: updatepage
      operations:
      - method: PATCH
        name: updatepage
        description: Notion Update page properties
        call: notion.updatepage
        with:
          page_id: rest.page_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /pages/{page_id}/properties/{property_id}
      name: retrievepageproperty
      operations:
      - method: GET
        name: retrievepageproperty
        description: Notion Retrieve a page property item
        call: notion.retrievepageproperty
        with:
          page_id: rest.page_id
          property_id: rest.property_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /databases
      name: createdatabase
      operations:
      - method: POST
        name: createdatabase
        description: Notion Create a database
        call: notion.createdatabase
        outputParameters:
        - type: object
          mapping: $.
    - path: /databases/{database_id}
      name: retrievedatabase
      operations:
      - method: GET
        name: retrievedatabase
        description: Notion Retrieve a database
        call: notion.retrievedatabase
        with:
          database_id: rest.database_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /databases/{database_id}
      name: updatedatabase
      operations:
      - method: PATCH
        name: updatedatabase
        description: Notion Update a database
        call: notion.updatedatabase
        with:
          database_id: rest.database_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /databases/{database_id}/query
      name: querydatabase
      operations:
      - method: POST
        name: querydatabase
        description: Notion Query a database
        call: notion.querydatabase
        with:
          database_id: rest.database_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /blocks/{block_id}
      name: retrieveblock
      operations:
      - method: GET
        name: retrieveblock
        description: Notion Retrieve a block
        call: notion.retrieveblock
        with:
          block_id: rest.block_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /blocks/{block_id}
      name: updateblock
      operations:
      - method: PATCH
        name: updateblock
        description: Notion Update a block
        call: notion.updateblock
        with:
          block_id: rest.block_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /blocks/{block_id}
      name: deleteblock
      operations:
      - method: DELETE
        name: deleteblock
        description: Notion Delete a block
        call: notion.deleteblock
        with:
          block_id: rest.block_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /blocks/{block_id}/children
      name: retrieveblockchildren
      operations:
      - method: GET
        name: retrieveblockchildren
        description: Notion Retrieve block children
        call: notion.retrieveblockchildren
        with:
          block_id: rest.block_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /blocks/{block_id}/children
      name: appendblockchildren
      operations:
      - method: PATCH
        name: appendblockchildren
        description: Notion Append block children
        call: notion.appendblockchildren
        with:
          block_id: rest.block_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /users
      name: listusers
      operations:
      - method: GET
        name: listusers
        description: Notion List all users
        call: notion.listusers
        outputParameters:
        - type: object
          mapping: $.
    - path: /users/{user_id}
      name: retrieveuser
      operations:
      - method: GET
        name: retrieveuser
        description: Notion Retrieve a user
        call: notion.retrieveuser
        with:
          user_id: rest.user_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /users/me
      name: retrievebotuser
      operations:
      - method: GET
        name: retrievebotuser
        description: Notion Retrieve the bot user
        call: notion.retrievebotuser
        outputParameters:
        - type: object
          mapping: $.
    - path: /search
      name: search
      operations:
      - method: POST
        name: search
        description: Notion Search by title
        call: notion.search
        outputParameters:
        - type: object
          mapping: $.
    - path: /comments
      name: listcomments
      operations:
      - method: GET
        name: listcomments
        description: Notion Retrieve comments
        call: notion.listcomments
        outputParameters:
        - type: object
          mapping: $.
    - path: /comments
      name: createcomment
      operations:
      - method: POST
        name: createcomment
        description: Notion Create a comment
        call: notion.createcomment
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: notion-mcp
    transport: http
    description: MCP adapter for Notion API for AI agent use.
    tools:
    - name: createpage
      description: Notion Create a page
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: notion.createpage
      outputParameters:
      - type: object
        mapping: $.
    - name: retrievepage
      description: Notion Retrieve a page
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: notion.retrievepage
      with:
        page_id: tools.page_id
        filter_properties: tools.filter_properties
      inputParameters:
      - name: page_id
        type: string
        description: The ID of the page to retrieve.
        required: true
      - name: filter_properties
        type: array
        description: A list of page property value IDs to include in the response. If provided, only the specified properties
          will be returned.
      outputParameters:
      - type: object
        mapping: $.
    - name: updatepage
      description: Notion Update page properties
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: notion.updatepage
      with:
        page_id: tools.page_id
      inputParameters:
      - name: page_id
        type: string
        description: The ID of the page to update.
        required: true
      outputParameters:
      - type: object
        mapping: $.
    - name: retrievepageproperty
      description: Notion Retrieve a page property item
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: notion.retrievepageproperty
      with:
        page_id: tools.page_id
        property_id: tools.property_id
        start_cursor: tools.start_cursor
        page_size: tools.page_size
      inputParameters:
      - name: page_id
        type: string
        description: The ID of the page.
        required: true
      - name: property_id
        type: string
        description: The ID of the property to retrieve.
        required: true
      - name: start_cursor
        type: string
        description: Pagination cursor for paginated property types. If supplied, returns results starting after the cursor.
      - name: page_size
        type: integer
        description: Maximum number of property items to return (max 100).
      outputParameters:
      - type: object
        mapping: $.
    - name: createdatabase
      description: Notion Create a database
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: notion.createdatabase
      outputParameters:
      - type: object
        mapping: $.
    - name: retrievedatabase
      description: Notion Retrieve a database
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: notion.retrievedatabase
      with:
        database_id: tools.database_id
      inputParameters:
      - name: database_id
        type: string
        description: The ID of the database to retrieve.
        required: true
      outputParameters:
      - type: object
        mapping: $.
    - name: updatedatabase
      description: Notion Update a database
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: notion.updatedatabase
      with:
        database_id: tools.database_id
      inputParameters:
      - name: database_id
        type: string
        description: The ID of the database to update.
        required: true
      outputParameters:
      - type: object
        mapping: $.
    - name: querydatabase
      description: Notion Query a database
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: notion.querydatabase
      with:
        database_id: tools.database_id
        filter_properties: tools.filter_properties
      inputParameters:
      - name: database_id
        type: string
        description: The ID of the database to query.
        required: true
      - name: filter_properties
        type: array
        description: A list of property IDs to include in the response. Only the specified properties will be returned for
          each page.
      outputParameters:
      - type: object
        mapping: $.
    - name: retrieveblock
      description: Notion Retrieve a block
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: notion.retrieveblock
      with:
        block_id: tools.block_id
      inputParameters:
      - name: block_id
        type: string
        description: The ID of the block to retrieve.
        required: true
      outputParameters:
      - type: object
        mapping: $.
    - name: updateblock
      description: Notion Update a block
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: notion.updateblock
      with:
        block_id: tools.block_id
      inputParameters:
      - name: block_id
        type: string
        description: The ID of the block to update.
        required: true
      outputParameters:
      - type: object
        mapping: $.
    - name: deleteblock
      description: Notion Delete a block
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: notion.deleteblock
      with:
        block_id: tools.block_id
      inputParameters:
      - name: block_id
        type: string
        description: The ID of the block to delete (archive).
        required: true
      outputParameters:
      - type: object
        mapping: $.
    - name: retrieveblockchildren
      description: Notion Retrieve block children
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: notion.retrieveblockchildren
      with:
        block_id: tools.block_id
        start_cursor: tools.start_cursor
        page_size: tools.page_size
      inputParameters:
      - name: block_id
        type: string
        description: The ID of the block whose children to retrieve. This can be a page ID to retrieve page content.
        required: true
      - name: start_cursor
        type: string
        description: Pagination cursor to continue fetching results.
      - name: page_size
        type: integer
        description: Maximum number of blocks to return (max 100).
      outputParameters:
      - type: object
        mapping: $.
    - name: appendblockchildren
      description: Notion Append block children
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: notion.appendblockchildren
      with:
        block_id: tools.block_id
      inputParameters:
      - name: block_id
        type: string
        description: The ID of the block to append children to. This can be a page ID to add content to a page.
        required: true
      outputParameters:
      - type: object
        mapping: $.
    - name: listusers
      description: Notion List all users
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: notion.listusers
      with:
        start_cursor: tools.start_cursor
        page_size: tools.page_size
      inputParameters:
      - name: start_cursor
        type: string
        description: Pagination cursor to continue fetching results.
      - name: page_size
        type: integer
        description: Maximum number of users to return (max 100).
      outputParameters:
      - type: object
        mapping: $.
    - name: retrieveuser
      description: Notion Retrieve a user
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: notion.retrieveuser
      with:
        user_id: tools.user_id
      inputParameters:
      - name: user_id
        type: string
        description: The ID of the user to retrieve.
        required: true
      outputParameters:
      - type: object
        mapping: $.
    - name: retrievebotuser
      description: Notion Retrieve the bot user
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: notion.retrievebotuser
      outputParameters:
      - type: object
        mapping: $.
    - name: search
      description: Notion Search by title
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: notion.search
      outputParameters:
      - type: object
        mapping: $.
    - name: listcomments
      description: Notion Retrieve comments
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: notion.listcomments
      with:
        block_id: tools.block_id
        start_cursor: tools.start_cursor
        page_size: tools.page_size
      inputParameters:
      - name: block_id
        type: string
        description: The ID of the block or page to retrieve comments for.
        required: true
      - name: start_cursor
        type: string
        description: Pagination cursor to continue fetching results.
      - name: page_size
        type: integer
        description: Maximum number of comments to return (max 100).
      outputParameters:
      - type: object
        mapping: $.
    - name: createcomment
      description: Notion Create a comment
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: notion.createcomment
      outputParameters:
      - type: object
        mapping: $.
binds:
- namespace: env
  keys:
    NOTION_TOKEN: NOTION_TOKEN