cotera
Logo

Notion

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

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
  • 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
  • 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

Appends child blocks to a parent block in Notion. Supports positioning blocks after specific blocks.

Operation Type: Mutation (Write)

Parameters:

  • blockId string (required): The ID of the parent block to append children to
  • children array of objects (required): Array of simple block objects to append as children
    • type string: The type of block (paragraph, heading_1, etc.)
    • content string: The text content for the block
  • after string (nullable): ID of the block to append after (optional)

Returns:

  • results array of objects: The newly created block objects
    • type string: The type of the block
    • object string: Always "block"
    • paragraph object (nullable): Paragraph block content
    • heading_1 object (nullable): Heading 1 block content
    • heading_2 object (nullable): Heading 2 block content
    • heading_3 object (nullable): Heading 3 block content

Example Usage:

{
  "blockId": "550e8400-e29b-41d4-a716-446655440000",
  "children": [
    {
      "type": "heading_1",
      "content": "Executive Summary"
    },
    {
      "type": "paragraph",
      "content": "Our Q1 marketing campaign exceeded expectations with a 25% increase in lead generation and 15% improvement in conversion rates."
    },
    {
      "type": "heading_2",
      "content": "Key Metrics"
    },
    {
      "type": "paragraph",
      "content": "Total leads generated: 1,250\nConversion rate: 18.5%\nCost per acquisition: $45"
    }
  ],
  "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
}

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 in databases with consistent properties
  • Update page titles and properties to reflect current project status
  • Search across all workspace content to find relevant documentation quickly

Content Organization:

  • Append new content blocks to existing pages for collaborative editing
  • Retrieve block children to analyze page structure and content hierarchy
  • Organize information with headings, paragraphs, and 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

Automated Workflows:

  • Search for pages matching specific criteria to trigger automated updates
  • Create standardized page templates with predefined properties and content structure
  • Retrieve and analyze page content for reporting and analytics purposes