Notion Tools — Ferrule Docs

MCPREST

POSTsearch/search

Search all pages and databases shared with the integration. Supports filtering by object type (page or database) and sorting by last_edited_time.

Request

Query Parameters

Name	Type	Required	Description
query	string	No	Text to search for.
filter	object	No	Filter results by object type. Example: { "value": "page", "property": "object" }
sort	object	No	Sort results. Example: { "direction": "descending", "timestamp": "last_edited_time" }
start_cursor	string	No	Cursor for pagination. Use next_cursor from a previous response.

Pagination

Name	Type	Required	Description
page_size	number	No	Number of results to return (max 100).

Response

objectstring

resultsarray

next_cursorobject

has_moreboolean

typeobject

Examples

1. Describe method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "describe_method",
    "arguments": {
      "service": "notion",
      "method": "search"
    }
  }
}

2. Call method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "call_notion",
    "arguments": {
      "method": "search",
      "params": {}
    }
  }
}

Request

POST https://app.ferrule.io/api/v1/notion/search
Authorization: Bearer <your-api-key>
Content-Type: application/json

Response

{
  "object": "...",
  "results": [],
  "next_cursor": null,
  "has_more": false,
  "type": null
}

GETget_page/pages/:page_id

Retrieve a page by its ID. Returns page properties, parent, and metadata.

Request

Path Parameters

Name	Type	Required	Description
page_id	string	Yes	The ID of the page to retrieve (UUID format, with or without dashes).

Response

objectstring

idstring

created_timeobject

last_edited_timeobject

created_byobject

last_edited_byobject

archivedobject

in_trashobject

iconobject

coverobject

propertiesobject

parentobject

urlobject

public_urlobject

Examples

1. Describe method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "describe_method",
    "arguments": {
      "service": "notion",
      "method": "get_page"
    }
  }
}

2. Call method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "call_notion",
    "arguments": {
      "method": "get_page",
      "params": {
        "page_id": "<page_id>"
      }
    }
  }
}

Request

GET https://app.ferrule.io/api/v1/notion/pages/:page_id
Authorization: Bearer <your-api-key>
Content-Type: application/json

Response

{
  "object": "...",
  "id": "...",
  "created_time": null,
  "last_edited_time": null,
  "created_by": null,
  "last_edited_by": null,
  "archived": null,
  "in_trash": null,
  "icon": null,
  "cover": null,
  "properties": null,
  "parent": null,
  "url": null,
  "public_url": null
}

POSTcreate_page/pages

Create a new page. The parent can be a database or another page. Properties must match the parent database schema if creating in a database.

Request

Query Parameters

Name	Type	Required	Description
parent	object	No	Parent of the page. Example: { "database_id": "..." } or { "page_id": "..." }.
properties	object	No	Page properties. When parent is a database, keys must match database property names.
children	object	No	Array of block objects to add as page content.
icon	object	No	Page icon. Example: { "emoji": "🎯" }.
cover	object	No	Page cover image as an external URL object.

Response

objectstring

idstring

created_timeobject

last_edited_timeobject

created_byobject

last_edited_byobject

archivedobject

in_trashobject

iconobject

coverobject

propertiesobject

parentobject

urlobject

public_urlobject

Examples

1. Describe method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "describe_method",
    "arguments": {
      "service": "notion",
      "method": "create_page"
    }
  }
}

2. Call method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "call_notion",
    "arguments": {
      "method": "create_page",
      "params": {}
    }
  }
}

Request

POST https://app.ferrule.io/api/v1/notion/pages
Authorization: Bearer <your-api-key>
Content-Type: application/json

Response

{
  "object": "...",
  "id": "...",
  "created_time": null,
  "last_edited_time": null,
  "created_by": null,
  "last_edited_by": null,
  "archived": null,
  "in_trash": null,
  "icon": null,
  "cover": null,
  "properties": null,
  "parent": null,
  "url": null,
  "public_url": null
}

PATCHupdate_page/pages/:page_id

Update a page's properties, icon, cover, or archived status.

Request

Path Parameters

Name	Type	Required	Description
page_id	string	Yes	The ID of the page to update.

Query Parameters

Name	Type	Required	Description
properties	object	No	Properties to update. Keys must match existing property names.
icon	object	No	Updated icon. Example: { "emoji": "✅" }.
cover	object	No	Updated cover image.
archived	boolean	No	Set to true to archive the page, false to unarchive.
in_trash	boolean	No	Set to true to move to trash.

Response

objectstring

idstring

created_timeobject

last_edited_timeobject

created_byobject

last_edited_byobject

archivedobject

in_trashobject

iconobject

coverobject

propertiesobject

parentobject

urlobject

public_urlobject

Examples

1. Describe method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "describe_method",
    "arguments": {
      "service": "notion",
      "method": "update_page"
    }
  }
}

2. Call method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "call_notion",
    "arguments": {
      "method": "update_page",
      "params": {
        "page_id": "<page_id>"
      }
    }
  }
}

Request

PATCH https://app.ferrule.io/api/v1/notion/pages/:page_id
Authorization: Bearer <your-api-key>
Content-Type: application/json

Response

{
  "object": "...",
  "id": "...",
  "created_time": null,
  "last_edited_time": null,
  "created_by": null,
  "last_edited_by": null,
  "archived": null,
  "in_trash": null,
  "icon": null,
  "cover": null,
  "properties": null,
  "parent": null,
  "url": null,
  "public_url": null
}

GETget_page_property/pages/:page_id/properties/:property_id

Retrieve a specific property value from a page. Useful for paginated properties like rich_text, title, relation, and rollup.

Request

Path Parameters

Name	Type	Required	Description
page_id	string	Yes	The ID of the page.
property_id	string	Yes	The ID of the property to retrieve. Found in the page's properties object.

Query Parameters

Name	Type	Required	Description
start_cursor	string	No	Cursor for paginated property values.

Pagination

Name	Type	Required	Description
page_size	number	No	Number of property items to return (max 100).

Response

unknown

Runtime output is unvalidated JSON (raw passthrough).

Examples

1. Describe method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "describe_method",
    "arguments": {
      "service": "notion",
      "method": "get_page_property"
    }
  }
}

2. Call method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "call_notion",
    "arguments": {
      "method": "get_page_property",
      "params": {
        "page_id": "<page_id>",
        "property_id": "<property_id>"
      }
    }
  }
}

Request

GET https://app.ferrule.io/api/v1/notion/pages/:page_id/properties/:property_id
Authorization: Bearer <your-api-key>
Content-Type: application/json

GETlist_databases/databases

List all databases shared with the integration. Returns a paginated list. Deprecated by Notion in favor of search with database filter, but still functional.

Request

Query Parameters

Name	Type	Required	Description
start_cursor	string	No	Cursor for pagination.

Pagination

Name	Type	Required	Description
page_size	number	No	Number of results to return (max 100).

Response

objectstring

resultsarray

next_cursorobject

has_moreboolean

typeobject

Examples

1. Describe method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "describe_method",
    "arguments": {
      "service": "notion",
      "method": "list_databases"
    }
  }
}

2. Call method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "call_notion",
    "arguments": {
      "method": "list_databases",
      "params": {}
    }
  }
}

Request

GET https://app.ferrule.io/api/v1/notion/databases
Authorization: Bearer <your-api-key>
Content-Type: application/json

Response

{
  "object": "...",
  "results": [],
  "next_cursor": null,
  "has_more": false,
  "type": null
}

GETget_database/databases/:database_id

Retrieve a database by its ID. Returns the database schema (properties), title, and metadata.

Request

Path Parameters

Name	Type	Required	Description
database_id	string	Yes	The ID of the database to retrieve.

Response

objectstring

idstring

created_timeobject

last_edited_timeobject

created_byobject

last_edited_byobject

titleobject

descriptionobject

iconobject

coverobject

propertiesobject

parentobject

urlobject

public_urlobject

archivedobject

in_trashobject

is_inlineobject

Examples

1. Describe method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "describe_method",
    "arguments": {
      "service": "notion",
      "method": "get_database"
    }
  }
}

2. Call method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "call_notion",
    "arguments": {
      "method": "get_database",
      "params": {
        "database_id": "<database_id>"
      }
    }
  }
}

Request

GET https://app.ferrule.io/api/v1/notion/databases/:database_id
Authorization: Bearer <your-api-key>
Content-Type: application/json

Response

{
  "object": "...",
  "id": "...",
  "created_time": null,
  "last_edited_time": null,
  "created_by": null,
  "last_edited_by": null,
  "title": null,
  "description": null,
  "icon": null,
  "cover": null,
  "properties": null,
  "parent": null,
  "url": null,
  "public_url": null,
  "archived": null,
  "in_trash": null,
  "is_inline": null
}

POSTquery_database/databases/:database_id/query

Query a database to retrieve pages that match filter and sort criteria. Supports compound filters, sorting by properties, and pagination.

Request

Path Parameters

Name	Type	Required	Description
database_id	string	Yes	The ID of the database to query.

Query Parameters

Name	Type	Required	Description
filter	object	No	Filter criteria. Example: { "property": "Status", "select": { "equals": "Done" } }.
sorts	object	No	Sort criteria array. Example: [{ "property": "Created", "direction": "descending" }].
start_cursor	string	No	Cursor for pagination.

Pagination

Name	Type	Required	Description
page_size	number	No	Number of results to return (max 100).

Response

objectstring

resultsarray

next_cursorobject

has_moreboolean

typeobject

Examples

1. Describe method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "describe_method",
    "arguments": {
      "service": "notion",
      "method": "query_database"
    }
  }
}

2. Call method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "call_notion",
    "arguments": {
      "method": "query_database",
      "params": {
        "database_id": "<database_id>"
      }
    }
  }
}

Request

POST https://app.ferrule.io/api/v1/notion/databases/:database_id/query
Authorization: Bearer <your-api-key>
Content-Type: application/json

Response

{
  "object": "...",
  "results": [],
  "next_cursor": null,
  "has_more": false,
  "type": null
}

POSTcreate_database/databases

Create a new database as a child of a page. Define the schema via properties.

Request

Query Parameters

Name	Type	Required	Description
parent	object	No	Parent page. Example: { "page_id": "..." }.
title	object	No	Database title as an array of rich text objects.
properties	object	No	Database property schema. Example: { "Name": { "title": {} }, "Tags": { "multi_select": { "options": [] } } }.
icon	object	No	Database icon.
cover	object	No	Database cover image.
is_inline	boolean	No	Whether the database is inline (true) or full page (false).

Response

objectstring

idstring

created_timeobject

last_edited_timeobject

created_byobject

last_edited_byobject

titleobject

descriptionobject

iconobject

coverobject

propertiesobject

parentobject

urlobject

public_urlobject

archivedobject

in_trashobject

is_inlineobject

Examples

1. Describe method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "describe_method",
    "arguments": {
      "service": "notion",
      "method": "create_database"
    }
  }
}

2. Call method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "call_notion",
    "arguments": {
      "method": "create_database",
      "params": {}
    }
  }
}

Request

POST https://app.ferrule.io/api/v1/notion/databases
Authorization: Bearer <your-api-key>
Content-Type: application/json

Response

{
  "object": "...",
  "id": "...",
  "created_time": null,
  "last_edited_time": null,
  "created_by": null,
  "last_edited_by": null,
  "title": null,
  "description": null,
  "icon": null,
  "cover": null,
  "properties": null,
  "parent": null,
  "url": null,
  "public_url": null,
  "archived": null,
  "in_trash": null,
  "is_inline": null
}

PATCHupdate_database/databases/:database_id

Update a database's title, description, properties schema, or archived status.

Request

Path Parameters

Name	Type	Required	Description
database_id	string	Yes	The ID of the database to update.

Query Parameters

Name	Type	Required	Description
title	object	No	Updated title as an array of rich text objects.
description	object	No	Updated description as an array of rich text objects.
properties	object	No	Property schema updates. Include only properties to add or modify. Set a property to null to delete it.
icon	object	No	Updated icon.
cover	object	No	Updated cover.
archived	boolean	No	Set to true to archive the database.
in_trash	boolean	No	Set to true to move to trash.

Response

objectstring

idstring

created_timeobject

last_edited_timeobject

created_byobject

last_edited_byobject

titleobject

descriptionobject

iconobject

coverobject

propertiesobject

parentobject

urlobject

public_urlobject

archivedobject

in_trashobject

is_inlineobject

Examples

1. Describe method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "describe_method",
    "arguments": {
      "service": "notion",
      "method": "update_database"
    }
  }
}

2. Call method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "call_notion",
    "arguments": {
      "method": "update_database",
      "params": {
        "database_id": "<database_id>"
      }
    }
  }
}

Request

PATCH https://app.ferrule.io/api/v1/notion/databases/:database_id
Authorization: Bearer <your-api-key>
Content-Type: application/json

Response

{
  "object": "...",
  "id": "...",
  "created_time": null,
  "last_edited_time": null,
  "created_by": null,
  "last_edited_by": null,
  "title": null,
  "description": null,
  "icon": null,
  "cover": null,
  "properties": null,
  "parent": null,
  "url": null,
  "public_url": null,
  "archived": null,
  "in_trash": null,
  "is_inline": null
}

GETget_block/blocks/:block_id

Retrieve a block by its ID. Returns block type and content.

Request

Path Parameters

Name	Type	Required	Description
block_id	string	Yes	The ID of the block to retrieve.

Response

objectstring

idstring

parentobject

typeobject

created_timeobject

last_edited_timeobject

created_byobject

last_edited_byobject

archivedobject

in_trashobject

has_childrenobject

Runtime output is unvalidated JSON (raw passthrough).

Examples

1. Describe method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "describe_method",
    "arguments": {
      "service": "notion",
      "method": "get_block"
    }
  }
}

2. Call method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "call_notion",
    "arguments": {
      "method": "get_block",
      "params": {
        "block_id": "<block_id>"
      }
    }
  }
}

Request

GET https://app.ferrule.io/api/v1/notion/blocks/:block_id
Authorization: Bearer <your-api-key>
Content-Type: application/json

Response

{
  "object": "...",
  "id": "...",
  "parent": null,
  "type": null,
  "created_time": null,
  "last_edited_time": null,
  "created_by": null,
  "last_edited_by": null,
  "archived": null,
  "in_trash": null,
  "has_children": null
}

PATCHupdate_block/blocks/:block_id

Update a block's content or archived status. The update payload depends on the block type.

Request

Path Parameters

Name	Type	Required	Description
block_id	string	Yes	The ID of the block to update.

Query Parameters

Name	Type	Required	Description
block_content	object	No	Block type-specific content to update. Pass the block type key and its new value. Example: { "paragraph": { "rich_text": [...] } }.
archived	boolean	No	Set to true to archive the block.
in_trash	boolean	No	Set to true to move to trash.

Response

objectstring

idstring

parentobject

typeobject

created_timeobject

last_edited_timeobject

created_byobject

last_edited_byobject

archivedobject

in_trashobject

has_childrenobject

Runtime output is unvalidated JSON (raw passthrough).

Examples

1. Describe method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "describe_method",
    "arguments": {
      "service": "notion",
      "method": "update_block"
    }
  }
}

2. Call method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "call_notion",
    "arguments": {
      "method": "update_block",
      "params": {
        "block_id": "<block_id>"
      }
    }
  }
}

Request

PATCH https://app.ferrule.io/api/v1/notion/blocks/:block_id
Authorization: Bearer <your-api-key>
Content-Type: application/json

Response

{
  "object": "...",
  "id": "...",
  "parent": null,
  "type": null,
  "created_time": null,
  "last_edited_time": null,
  "created_by": null,
  "last_edited_by": null,
  "archived": null,
  "in_trash": null,
  "has_children": null
}

DELETEdelete_block/blocks/:block_id

Delete (archive) a block by its ID. The block can be a page, database, or any content block.

Request

Path Parameters

Name	Type	Required	Description
block_id	string	Yes	The ID of the block to delete.

Response

objectstring

idstring

parentobject

typeobject

created_timeobject

last_edited_timeobject

created_byobject

last_edited_byobject

archivedobject

in_trashobject

has_childrenobject

Runtime output is unvalidated JSON (raw passthrough).

Examples

1. Describe method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "describe_method",
    "arguments": {
      "service": "notion",
      "method": "delete_block"
    }
  }
}

2. Call method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "call_notion",
    "arguments": {
      "method": "delete_block",
      "params": {
        "block_id": "<block_id>"
      }
    }
  }
}

Request

DELETE https://app.ferrule.io/api/v1/notion/blocks/:block_id
Authorization: Bearer <your-api-key>
Content-Type: application/json

Response

{
  "object": "...",
  "id": "...",
  "parent": null,
  "type": null,
  "created_time": null,
  "last_edited_time": null,
  "created_by": null,
  "last_edited_by": null,
  "archived": null,
  "in_trash": null,
  "has_children": null
}

GETlist_block_children/blocks/:block_id/children

List the children blocks of a given block (page, database, or other block with children). Returns a paginated list.

Request

Path Parameters

Name	Type	Required	Description
block_id	string	Yes	The ID of the parent block. Can be a page ID to get page content.

Query Parameters

Name	Type	Required	Description
start_cursor	string	No	Cursor for pagination.

Pagination

Name	Type	Required	Description
page_size	number	No	Number of blocks to return (max 100).

Response

objectstring

resultsarray

next_cursorobject

has_moreboolean

typeobject

Runtime output is unvalidated JSON (raw passthrough).

Examples

1. Describe method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "describe_method",
    "arguments": {
      "service": "notion",
      "method": "list_block_children"
    }
  }
}

2. Call method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "call_notion",
    "arguments": {
      "method": "list_block_children",
      "params": {
        "block_id": "<block_id>"
      }
    }
  }
}

Request

GET https://app.ferrule.io/api/v1/notion/blocks/:block_id/children
Authorization: Bearer <your-api-key>
Content-Type: application/json

Response

{
  "object": "...",
  "results": [],
  "next_cursor": null,
  "has_more": false,
  "type": null
}

PATCHappend_block_children/blocks/:block_id/children

Append new children blocks to a parent block. Use this to add content to pages or nested blocks.

Request

Path Parameters

Name	Type	Required	Description
block_id	string	Yes	The ID of the parent block to append children to.

Query Parameters

Name	Type	Required	Description
children	object	No	Array of block objects to append. Example: [{ "paragraph": { "rich_text": [{ "text": { "content": "Hello" } }] } }].
after	string	No	ID of an existing block to insert the new children after. If omitted, children are appended at the end.

Response

objectstring

resultsarray

next_cursorobject

has_moreboolean

typeobject

Runtime output is unvalidated JSON (raw passthrough).

Examples

1. Describe method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "describe_method",
    "arguments": {
      "service": "notion",
      "method": "append_block_children"
    }
  }
}

2. Call method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "call_notion",
    "arguments": {
      "method": "append_block_children",
      "params": {
        "block_id": "<block_id>"
      }
    }
  }
}

Request

PATCH https://app.ferrule.io/api/v1/notion/blocks/:block_id/children
Authorization: Bearer <your-api-key>
Content-Type: application/json

Response

{
  "object": "...",
  "results": [],
  "next_cursor": null,
  "has_more": false,
  "type": null
}

GETlist_users/users

List all users in the workspace. Includes people and bots.

Request

Query Parameters

Name	Type	Required	Description
start_cursor	string	No	Cursor for pagination.

Pagination

Name	Type	Required	Description
page_size	number	No	Number of users to return (max 100).

Response

objectstring

resultsarray

next_cursorobject

has_moreboolean

typeobject

Examples

1. Describe method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "describe_method",
    "arguments": {
      "service": "notion",
      "method": "list_users"
    }
  }
}

2. Call method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "call_notion",
    "arguments": {
      "method": "list_users",
      "params": {}
    }
  }
}

Request

GET https://app.ferrule.io/api/v1/notion/users
Authorization: Bearer <your-api-key>
Content-Type: application/json

Response

{
  "object": "...",
  "results": [],
  "next_cursor": null,
  "has_more": false,
  "type": null
}

GETget_user/users/:user_id

Retrieve a user by their ID.

Request

Path Parameters

Name	Type	Required	Description
user_id	string	Yes	The ID of the user to retrieve.

Response

objectstring

idstring

typeobject

nameobject

avatar_urlobject

Examples

1. Describe method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "describe_method",
    "arguments": {
      "service": "notion",
      "method": "get_user"
    }
  }
}

2. Call method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "call_notion",
    "arguments": {
      "method": "get_user",
      "params": {
        "user_id": "<user_id>"
      }
    }
  }
}

Request

GET https://app.ferrule.io/api/v1/notion/users/:user_id
Authorization: Bearer <your-api-key>
Content-Type: application/json

Response

{
  "object": "...",
  "id": "...",
  "type": null,
  "name": null,
  "avatar_url": null
}

GETget_me/users/me

Retrieve the bot user associated with the current integration token.

Request

No input parameters.

Response

objectstring

idstring

typeobject

nameobject

avatar_urlobject

Examples

1. Describe method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "describe_method",
    "arguments": {
      "service": "notion",
      "method": "get_me"
    }
  }
}

2. Call method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "call_notion",
    "arguments": {
      "method": "get_me",
      "params": {}
    }
  }
}

Request

GET https://app.ferrule.io/api/v1/notion/users/me
Authorization: Bearer <your-api-key>
Content-Type: application/json

Response

{
  "object": "...",
  "id": "...",
  "type": null,
  "name": null,
  "avatar_url": null
}

GETlist_comments/comments

List comments on a block (page or other block). Requires the integration to have comment read capabilities.

Request

Query Parameters

Name	Type	Required	Description
block_id	string	No	The ID of the block to list comments for.
start_cursor	string	No	Cursor for pagination.

Pagination

Name	Type	Required	Description
page_size	number	No	Number of comments to return (max 100).

Response

objectstring

resultsarray

next_cursorobject

has_moreboolean

typeobject

Examples

1. Describe method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "describe_method",
    "arguments": {
      "service": "notion",
      "method": "list_comments"
    }
  }
}

2. Call method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "call_notion",
    "arguments": {
      "method": "list_comments",
      "params": {}
    }
  }
}

Request

GET https://app.ferrule.io/api/v1/notion/comments
Authorization: Bearer <your-api-key>
Content-Type: application/json

Response

{
  "object": "...",
  "results": [],
  "next_cursor": null,
  "has_more": false,
  "type": null
}

POSTcreate_comment/comments

Create a comment on a page or in an existing discussion thread. Either parent (with page_id) or discussion_id must be provided.

Request

Query Parameters

Name	Type	Required	Description
parent	object	No	Parent page to create a top-level comment on. Example: { "page_id": "..." }.
discussion_id	string	No	ID of an existing discussion thread to reply to.
rich_text	object	No	Comment body as an array of rich text objects. Example: [{ "text": { "content": "This is a comment" } }].

Response

objectstring

idstring

parentobject

discussion_idobject

created_timeobject

last_edited_timeobject

created_byobject

rich_textobject

Examples

1. Describe method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "describe_method",
    "arguments": {
      "service": "notion",
      "method": "create_comment"
    }
  }
}

2. Call method

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "call_notion",
    "arguments": {
      "method": "create_comment",
      "params": {}
    }
  }
}

Request

POST https://app.ferrule.io/api/v1/notion/comments
Authorization: Bearer <your-api-key>
Content-Type: application/json

Response

{
  "object": "...",
  "id": "...",
  "parent": null,
  "discussion_id": null,
  "created_time": null,
  "last_edited_time": null,
  "created_by": null,
  "rich_text": null
}