# Notion

> Integrate with Notion to create, retrieve, update pages, query databases, manage block content with markdown, and search.

Source: https://cotera.co/docs/reference/tools/individual-tools/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](https://developers.notion.com/docs/create-a-notion-integration) 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:**

```json
{}
```

***

## 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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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](https://developers.notion.com/reference/post-database-query-filter) 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:**

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

***

## Search

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:**

```json
{
  "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