cotera
Logo

Notion

Authentication Type: API Key Description: Integrate with Notion to create, retrieve, update pages, query databases, manage block content with markdown, and search.

Authentication

To authenticate, you'll need to create a Notion internal integration:

  1. Follow the Notion integration guide to create an internal integration (you can name it anything)
  2. Give the integration access to the databases you want it to access
  3. Copy the API token from your integration settings

Users

The users of your workspace.

List All Users

Get a list of all the users for the workspace.

Operation Type: Query (Read)

Parameters:

  • None

Returns:

  • results array of objects: Array of workspace users
    • id string: User ID
    • object string: Always "user"
    • name string (nullable): User display name
    • avatar_url string (nullable): User avatar image URL
    • person object (nullable): Person details
      • email string (nullable): User email address

Example Usage:

{}

Pages

Operations for managing Notion pages.

Create Page

Creates a new page in Notion with the specified title, content, and properties.

Operation Type: Mutation (Write)

Parameters:

  • parentDatabaseId string (required): The ID of the parent database to create the page in
  • title string (required): The title of the page
  • content string (nullable): The content/body of the page in markdown format. Supports headings, lists, code blocks, tables, and inline formatting.
  • properties array of objects (nullable): Additional properties for the page (key-value pairs)
    • key string: Property name
    • value string: Property value

Returns:

  • pageId string: The ID of the created page
  • url string: The URL of the created page
  • title string: The title of the created page

Example Usage:

{
  "parentDatabaseId": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Q1 2024 Marketing Campaign",
  "content": "This page outlines our marketing strategy for the first quarter of 2024, including target audiences, budget allocation, and key performance indicators.",
  "properties": [
    {
      "key": "Status",
      "value": "In Progress"
    },
    {
      "key": "Owner",
      "value": "Marketing Team"
    },
    {
      "key": "Priority",
      "value": "High"
    }
  ]
}

Retrieve Page

Retrieves a page from Notion by its ID, including content and properties.

Operation Type: Query (Read)

Parameters:

  • pageId string (required): The ID of the page to retrieve

Returns:

  • pageId string: The ID of the page
  • title string: The title of the page
  • content string (nullable): The content of the page in markdown format
  • url string: The URL of the page
  • lastEditedTime string: When the page was last edited
  • properties array of objects (nullable): The properties of the page
    • key string: Property name
    • value string: Property value

Example Usage:

{
  "pageId": "550e8400-e29b-41d4-a716-446655440000"
}

Update Page

Updates an existing page in Notion with new title or properties.

Operation Type: Mutation (Write)

Parameters:

  • pageId string (required): The ID of the page to update
  • title string (nullable): The new title of the page
  • properties array of objects (nullable): Updated properties for the page
    • key string: Property name
    • value string: Property value

Returns:

  • pageId string: The ID of the updated page
  • url string: The URL of the updated page
  • title string (nullable): The title of the updated page
  • lastEditedTime string: When the page was last edited

Example Usage:

{
  "pageId": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Q1 2024 Marketing Campaign - Final",
  "properties": [
    {
      "key": "Status",
      "value": "Completed"
    },
    {
      "key": "Completion Date",
      "value": "2024-03-31"
    }
  ]
}

Blocks

Operations for managing Notion blocks and their children.

Append Block Children

Append content to a Notion page or block using markdown. Supports headings, lists, to-dos, quotes, code blocks, tables, and inline formatting.

Operation Type: Mutation (Write)

Parameters:

  • blockId string (required): The ID of the parent block to append children to
  • markdown string (required): Markdown content to append. Supports headings (#, ##, ###), lists (-, 1.), to-dos (- [x]), quotes (>), code blocks (```), tables (| |), and inline formatting (**bold**, *italic*, ~~strike~~, `code`, [link](url)).
  • after string (nullable): ID of the block to append after (optional)

Returns:

  • blockCount number: The number of blocks that were appended

Example Usage:

{
  "blockId": "550e8400-e29b-41d4-a716-446655440000",
  "markdown": "# Executive Summary\n\nOur Q1 marketing campaign exceeded expectations with a **25% increase** in lead generation.\n\n## Key Metrics\n\n- Total leads generated: 1,250\n- Conversion rate: 18.5%\n- Cost per acquisition: $45\n\n## Next Steps\n\n1. Review budget allocation\n2. Plan Q2 campaigns",
  "after": null
}

Retrieve Block Children

Retrieves the child blocks of a parent block in Notion with pagination support.

Operation Type: Query (Read)

Parameters:

  • blockId string (required): The ID of the parent block to retrieve children from
  • startCursor string (nullable): Pagination cursor for starting position
  • pageSize number (nullable): Number of children to retrieve (max 100)

Returns:

  • results array of objects: The child block objects
  • hasMore boolean: Whether there are more results available
  • nextCursor string (nullable): Cursor for next page of results

Example Usage:

{
  "blockId": "550e8400-e29b-41d4-a716-446655440000",
  "startCursor": null,
  "pageSize": 50
}

Databases

Operations for querying Notion databases.

Query Database

Query a Notion database with optional filters, sorts, and pagination. Returns pages with their properties extracted as readable strings.

Operation Type: Query (Read)

Parameters:

  • databaseId string (required): The ID of the database to query
  • filter object (nullable): Notion filter object (passed through to the API). See Notion filter documentation for the full filter syntax.
  • sorts array of objects (nullable): Sort criteria
    • property string: The property name to sort by
    • direction string: Sort direction: "ascending" or "descending"
  • startCursor string (nullable): Pagination cursor for next page of results
  • pageSize number (nullable): Number of results to return (max 100, default 50)

Returns:

  • results array of objects: The matching pages
    • id string: The page ID
    • title string: The page title
    • url string: The page URL
    • properties object: Page properties as readable key-value pairs
  • hasMore boolean: Whether there are more results available
  • nextCursor string (nullable): Cursor for fetching the next page of results

Example Usage:

{
  "databaseId": "550e8400-e29b-41d4-a716-446655440000",
  "filter": {
    "property": "Status",
    "select": {
      "equals": "In Progress"
    }
  },
  "sorts": [
    {
      "property": "Priority",
      "direction": "descending"
    }
  ],
  "startCursor": null,
  "pageSize": 25
}

Search operations for finding pages and databases in Notion.

Search Content

Searches for pages and databases in Notion using the provided query. Supports filtering, sorting, and pagination.

Operation Type: Query (Read)

Parameters:

  • query string (required): The search query to find pages and databases
  • filter object (nullable): Filter criteria with property and value
    • property string: Property to filter by
    • value string: Filter value
  • sortBy string (nullable): Sort direction: ascending or descending
  • pageSize number (nullable): Number of results to return (max 100)
  • startCursor string (nullable): Pagination cursor for next page of results

Returns:

  • results array of objects: The search results
    • id string: The ID of the result
    • type string: The type of result (page or database)
    • title string: The title of the result
    • url string: The URL of the result
    • lastEditedTime string: When the result was last edited
  • hasMore boolean: Whether there are more results available
  • nextCursor string (nullable): Cursor for next page of results

Example Usage:

{
  "query": "marketing campaign Q1 2024",
  "filter": {
    "property": "object",
    "value": "page"
  },
  "sortBy": "descending",
  "pageSize": 25,
  "startCursor": null
}

Common Use Cases

Knowledge Base Management:

  • Create structured documentation pages with rich markdown content including headings, lists, and code blocks
  • Update page titles and properties to reflect current project status
  • Search across all workspace content to find relevant documentation quickly

Database-Driven Workflows:

  • Query databases with filters to find pages matching specific criteria (e.g., all "In Progress" tasks)
  • Sort and paginate through large databases efficiently
  • Extract page properties as readable strings for reporting and automation

Content Organization:

  • Append rich content to existing pages using markdown (headings, lists, tables, code blocks)
  • Retrieve page content as markdown for analysis or transformation
  • Organize information with structured content blocks

Team Collaboration:

  • List workspace users to understand team composition and access levels
  • Create project pages with assigned owners and status tracking properties
  • Update page properties to reflect changing priorities and project milestones