# Notion Integration via LowCodeAPI

## Overview

Notion is a productivity and note-taking platform for creating documents, databases, wikis, and project management workspaces.

## Base Endpoint

```
https://api.lowcodeapi.com/notion/
```

## Authentication

LowCodeAPI handles authentication automatically. You only need to:

1. **Sign up** at https://www.notion.so/
2. **Connect your account** in LowCodeAPI dashboard
3. **Use your `api_token`** in all requests

The `api_token` is your LowCodeAPI authentication token. LowCodeAPI will automatically:
- Fetch your Notion API key from database
- Apply it to each request with proper Bearer token header
- Include Notion-Version header

**Auth Type**: `API Key` (Bearer Token)

## API Categories

- File Sharing & Collaboration
- Pages
- Blocks
- Databases
- Users

## Common Endpoints

### Category: Pages

#### Retrieve a Page

**Method**: `GET` | **LowCodeAPI Path**: `/v1/pages/page_id`

**Full URL**:
```
https://api.lowcodeapi.com/notion/v1/pages/page_id?page_id={page_id}&api_token={api_token}
```

**Description**: Retrieve page properties and other information. To retrieve page content, use the blocks API.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page_id` | string | Yes | Identifier for a Notion page |
| `api_token` | string | Yes | Your LowCodeAPI authentication token |
| `filter_properties` | string | No | Limit response to specific page property values |

**Example Request**:
```bash
# Get page properties and metadata
# page_id from Notion page URL
curl -X GET "https://api.lowcodeapi.com/notion/v1/pages/page_id?page_id=PAGE_ID&api_token=YOUR_API_TOKEN"
```

**Example Response**:
```json
{
  "id": "PAGE_ID",
  "object": "page",
  "created_time": "2024-01-01T00:00:00.000Z",
  "last_edited_time": "2024-01-02T00:00:00.000Z",
  "properties": {
    "Name": {
      "title": [
        {
          "text": {
            "content": "My Page"
          }
        }
      ]
    }
  }
}
```

**Official Documentation**: https://developers.notion.com/reference/retrieve-a-page

---

#### Update Page Properties

**Method**: `PATCH` | **LowCodeAPI Path**: `/v1/pages/page_id`

**Full URL**:
```
https://api.lowcodeapi.com/notion/v1/pages/page_id?page_id={page_id}&api_token={api_token}
```

**Description**: Update page properties, icon, and cover. This API only updates properties, not page content.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page_id` | string | Yes | Identifier for a Notion page |
| `api_token` | string | Yes | Your LowCodeAPI authentication token |

**Request Body Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `properties` | object | No | Property values of the page |
| `archived` | boolean | No | Whether the page is archived (deleted) |
| `icon` | object | No | Page icon |
| `cover` | object | No | Page cover image |

**Example Request**:
```bash
# Update page properties
curl -X PATCH "https://api.lowcodeapi.com/notion/v1/pages/page_id?page_id=PAGE_ID&api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "Name": {
        "title": [
          {
            "text": {
              "content": "Updated Page Title"
            }
          }
        ]
      },
      "Status": {
        "select": {
          "name": "In Progress"
        }
      }
    }
  }'
```

**Official Documentation**: https://developers.notion.com/reference/patch-page

---

### Category: Blocks

#### Retrieve Block Children

**Method**: `GET` | **LowCodeAPI Path**: `/v1/blocks/block_id/children`

**Full URL**:
```
https://api.lowcodeapi.com/notion/v1/blocks/block_id/children?block_id={block_id}&api_token={api_token}
```

**Description**: Retrieve the children (content) of a block. Use this to get page content.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `block_id` | string | Yes | Block or page ID |
| `api_token` | string | Yes | Your LowCodeAPI authentication token |
| `start_cursor` | string | No | Paginate through results |
| `page_size` | number | No | Number of results (default: 100) |

**Example Request**:
```bash
# Get page content using page_id as block_id
curl -X GET "https://api.lowcodeapi.com/notion/v1/blocks/block_id/children?block_id=PAGE_ID&page_size=50&api_token=YOUR_API_TOKEN"
```

**Official Documentation**: https://developers.notion.com/reference/retrieve-block-children

---

#### Retrieve a Block

**Method**: `GET` | **LowCodeAPI Path**: `/v1/blocks/block_id`

**Full URL**:
```
https://api.lowcodeapi.com/notion/v1/blocks/block_id?block_id={block_id}&api_token={api_token}
```

**Description**: Retrieve a block object.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `block_id` | string | Yes | Identifier for a Notion block |
| `api_token` | string | Yes | Your LowCodeAPI authentication token |

**Example Request**:
```bash
# Get individual block details
curl -X GET "https://api.lowcodeapi.com/notion/v1/blocks/block_id?block_id=BLOCK_ID&api_token=YOUR_API_TOKEN"
```

**Official Documentation**: https://developers.notion.com/reference/retrieve-a-block

---

#### Append Block Children

**Method**: `PATCH` | **LowCodeAPI Path**: `/v1/blocks/block_id/children`

**Full URL**:
```
https://api.lowcodeapi.com/notion/v1/blocks/block_id/children?block_id={block_id}&api_token={api_token}
```

**Description**: Create and append new blocks to a parent block or page. This adds content to a page.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `block_id` | string | Yes | Block or page ID to append to |
| `api_token` | string | Yes | Your LowCodeAPI authentication token |

**Request Body Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `children` | array | Yes | Array of block objects to append |

**Example Request**:
```bash
# Add content to a page
curl -X PATCH "https://api.lowcodeapi.com/notion/v1/blocks/block_id/children?block_id=PAGE_ID&api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [
      {
        "object": "block",
        "type": "heading_2",
        "heading_2": {
          "rich_text": [
            {
              "type": "text",
              "text": {
                "content": "New Section"
              }
            }
          ]
        }
      },
      {
        "object": "block",
        "type": "paragraph",
        "paragraph": {
          "rich_text": [
            {
              "type": "text",
              "text": {
                "content": "This is a new paragraph added to the page."
              }
            }
          ]
        }
      }
    ]
  }'
```

**Official Documentation**: https://developers.notion.com/reference/append-block-children

---

#### Delete a Block

**Method**: `DELETE` | **LowCodeAPI Path**: `/v1/blocks/block_id`

**Full URL**:
```
https://api.lowcodeapi.com/notion/v1/blocks/block_id?block_id={block_id}&api_token={api_token}
```

**Description**: Set a block (including pages) to archived: true.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `block_id` | string | Yes | Identifier for a Notion block |
| `api_token` | string | Yes | Your LowCodeAPI authentication token |

**Example Request**:
```bash
# Archive/delete a block
curl -X DELETE "https://api.lowcodeapi.com/notion/v1/blocks/block_id?block_id=BLOCK_ID&api_token=YOUR_API_TOKEN"
```

**Official Documentation**: https://developers.notion.com/reference/delete-a-block

---

### Category: Databases

#### Query a Database

**Method**: `POST` | **LowCodeAPI Path**: `/v1/databases/database_id/query`

**Full URL**:
```
https://api.lowcodeapi.com/notion/v1/databases/database_id/query?database_id={database_id}&api_token={api_token}
```

**Description**: Get a list of pages in a database with filtering and sorting.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `database_id` | string | Yes | Database ID |
| `api_token` | string | Yes | Your LowCodeAPI authentication token |

**Request Body Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `filter` | object | No | Filter criteria for the query |
| `sorts` | array | No | Sort criteria |
| `start_cursor` | string | No | Paginate through results |
| `page_size` | number | No | Number of results (max: 100) |

**Example Request**:
```bash
# Query database with filters
curl -X POST "https://api.lowcodeapi.com/notion/v1/databases/database_id/query?database_id=DATABASE_ID&api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "property": "Status",
      "select": {
        "equals": "In Progress"
      }
    },
    "sorts": [
      {
        "property": "Last Edited",
        "direction": "descending"
      }
    ],
    "page_size": 50
  }'
```

**Official Documentation**: https://developers.notion.com/reference/post-database-query

---

#### Retrieve a Database

**Method**: `GET` | **LowCodeAPI Path**: `/v1/databases/database_id`

**Full URL**:
```
https://api.lowcodeapi.com/notion/v1/databases/database_id?database_id={database_id}&api_token={api_token}
```

**Description**: Retrieve database schema and metadata.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `database_id` | string | Yes | Database ID |
| `api_token` | string | Yes | Your LowCodeAPI authentication token |

**Example Request**:
```bash
# Get database structure and properties
curl -X GET "https://api.lowcodeapi.com/notion/v1/databases/database_id?database_id=DATABASE_ID&api_token=YOUR_API_TOKEN"
```

**Official Documentation**: https://developers.notion.com/reference/retrieve-a-database

---

#### Create a Database

**Method**: `POST` | **LowCodeAPI Path**: `/v1/databases`

**Full URL**:
```
https://api.lowcodeapi.com/notion/v1/databases?api_token={api_token}
```

**Description**: Create a database as a subpage in a parent page or in an existing workspace.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `api_token` | string | Yes | Your LowCodeAPI authentication token |

**Request Body Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `parent` | object | Yes | Parent page or workspace |
| `properties` | object | Yes | Database property schema |
| `title` | array | Yes | Database title |

**Example Request**:
```bash
# Create new database in a page
curl -X POST "https://api.lowcodeapi.com/notion/v1/databases?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {
      "type": "page_id",
      "page_id": "PARENT_PAGE_ID"
    },
    "properties": {
      "Name": {
        "title": {}
      },
      "Status": {
        "select": {
          "options": [
            {"name": "Not Started"},
            {"name": "In Progress"},
            {"name": "Done"}
          ]
        }
      }
    },
    "title": [
      {
        "text": {
          "content": "Project Tracker"
        }
      }
    ]
  }'
```

**Official Documentation**: https://developers.notion.com/reference/create-a-database

---

## Usage Examples

### Example 1: Create and Update a Page

Complete workflow for page creation and updates.

```bash
# Step 1: Get page properties
# page_id from Notion page URL
curl -X GET "https://api.lowcodeapi.com/notion/v1/pages/page_id?page_id=PAGE_ID&api_token=YOUR_API_TOKEN"

# Step 2: Update page properties
curl -X PATCH "https://api.lowcodeapi.com/notion/v1/pages/page_id?page_id=PAGE_ID&api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "Status": {
        "select": {
          "name": "Completed"
        }
      },
      "Priority": {
        "number": 1
      }
    }
  }'

# Step 3: Add content blocks to the page
curl -X PATCH "https://api.lowcodeapi.com/notion/v1/blocks/block_id/children?block_id=PAGE_ID&api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [
      {
        "type": "heading_1",
        "heading_1": {
          "rich_text": [{"type": "text", "text": {"content": "Project Overview"}}]
        }
      },
      {
        "type": "to_do",
        "to_do": {
          "rich_text": [{"type": "text", "text": {"content": "Research competitors"}}],
          "checked": false
        }
      }
    ]
  }'
```

### Example 2: Query and Filter Database

Search and organize database content.

```bash
# Query database with multiple filters
curl -X POST "https://api.lowcodeapi.com/notion/v1/databases/database_id/query?database_id=DATABASE_ID&api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "and": [
        {
          "property": "Status",
          "select": {
            "equals": "In Progress"
          }
        },
        {
          "property": "Priority",
          "number": {
            "greater_than_or_equal_to": 2
          }
        }
      ]
    },
    "sorts": [
      {
        "property": "Due Date",
        "direction": "ascending"
      }
    ]
  }'

# Get database schema
curl -X GET "https://api.lowcodeapi.com/notion/v1/databases/database_id?database_id=DATABASE_ID&api_token=YOUR_API_TOKEN"
```

### Example 3: Read Page Content

Retrieve and navigate page content.

```bash
# Get all blocks (content) of a page
curl -X GET "https://api.lowcodeapi.com/notion/v1/blocks/block_id/children?block_id=PAGE_ID&page_size=100&api_token=YOUR_API_TOKEN"

# Get specific block details
# Use block_id from children response
curl -X GET "https://api.lowcodeapi.com/notion/v1/blocks/block_id?block_id=BLOCK_ID&api_token=YOUR_API_TOKEN"
```

## Complete Endpoint Reference

For a complete list of all endpoints and their parameters, refer to:
- **OpenAPI Definition**: `https://backend.lowcodeapi.com/notion/definition`
- **Official Provider Documentation**: https://developers.notion.com/

## Rate Limits & Best Practices

- Use pagination for large databases and page content
- Properties can only be updated if the page belongs to a database
- Use blocks API to update page content
- Archive instead of delete to preserve data

## Error Handling

Standard HTTP status codes apply. Common errors include invalid page/database IDs, permission issues, or malformed property data.