> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreflux.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Notion

> Client-mode REST API connector for a curated Notion slice: create/update pages, query databases, users/me smoke, retrieve database, and search

Technical Preview

## Overview

A client-mode connector for a **curated work-management / documentation** slice of the [Notion REST API](https://developers.notion.com/reference/intro):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST pages | `POST /v1/pages` | Create page / database row (device log) |
| PATCH pages/\{id} | `PATCH /v1/pages/{page_id}` | Update page properties |
| POST databases/\{id}/query | `POST /v1/databases/{database_id}/query` | Query / filter / sort rows |
| GET users/me (smoke) | `GET /v1/users/me` | Credential check → `id` |
| GET databases/\{id} | `GET /v1/databases/{database_id}` | Retrieve database |
| POST search | `POST /v1/search` | Search shared pages/databases |

Default `BASE_ADDRESS` is `https://api.notion.com`. Topics use `devops/notion/<object>/<verb>`.

Every request must include **`Notion-Version: 2022-06-28`**. This template pins that version so catalog `POST /v1/databases/{id}/query` remains valid; Notion deprecates that path under API versions `2025-09-03` and later (databases → data sources).

> [!NOTE]
>
> Auth is **Bearer** integration secret, OAuth 2.0 access token, or PAT (`Authorization: Bearer …`). Prefer Hub secret `NOTION_API_TOKEN` (aliases `NOTION_TOKEN`, `NOTION_INTEGRATION_TOKEN`, `NOTION_ACCESS_TOKEN`). Status remains blocked until an authenticated live smoke succeeds. Share target databases/pages with the integration or Notion returns HTTP 404.

## Basic Syntax

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Notion REST API
# Auth: Bearer {value.json.access_token}
# BASE_ADDRESS: https://api.notion.com
# Notion-Version: 2022-06-28

DEFINE ROUTE NotionRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.notion.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Getuserme
        WITH SOURCE_TOPIC "devops/notion/user/me"
        WITH DESTINATION_TOPIC "devops/notion/user/me/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/users/me"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Notion-Version" "2022-06-28"
    ADD EVENT Createpage
        WITH SOURCE_TOPIC "devops/notion/page/create"
        WITH DESTINATION_TOPIC "devops/notion/page/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/pages"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Notion-Version" "2022-06-28"
        WITH BODY "{payload}"
    ADD EVENT Updatepage
        WITH SOURCE_TOPIC "devops/notion/page/update"
        WITH DESTINATION_TOPIC "devops/notion/page/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/v1/pages/{value.json.page_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Notion-Version" "2022-06-28"
        WITH BODY "{payload}"
    ADD EVENT Querydatabase
        WITH SOURCE_TOPIC "devops/notion/database/query"
        WITH DESTINATION_TOPIC "devops/notion/database/query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/databases/{value.json.database_id}/query"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Notion-Version" "2022-06-28"
        WITH BODY "{payload}"
    ADD EVENT Getdatabase
        WITH SOURCE_TOPIC "devops/notion/database/get"
        WITH DESTINATION_TOPIC "devops/notion/database/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/databases/{value.json.database_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Notion-Version" "2022-06-28"
    ADD EVENT Search
        WITH SOURCE_TOPIC "devops/notion/search"
        WITH DESTINATION_TOPIC "devops/notion/search/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/search"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Notion-Version" "2022-06-28"
        WITH BODY "{payload}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Getuserme | GET | `/v1/users/me` | `devops/notion/user/me` | `devops/notion/user/me/response` |
| Createpage | POST | `/v1/pages` | `devops/notion/page/create` | `devops/notion/page/create/response` |
| Updatepage | PATCH | `/v1/pages/{page_id}` | `devops/notion/page/update` | `devops/notion/page/update/response` |
| Querydatabase | POST | `/v1/databases/{database_id}/query` | `devops/notion/database/query` | `devops/notion/database/query/response` |
| Getdatabase | GET | `/v1/databases/{database_id}` | `devops/notion/database/get` | `devops/notion/database/get/response` |
| Search | POST | `/v1/search` | `devops/notion/search` | `devops/notion/search/response` |

## Auth

1. Create an [internal integration](https://www.notion.so/my-integrations) (or use OAuth / PAT) and copy the secret.
2. Set connector `BASE_ADDRESS` to `https://api.notion.com`.
3. Pass `access_token` on MQTT JSON payloads so the Bearer header resolves. For path params, also pass `page_id` / `database_id`.
4. Store secrets in Hub / `GET SECRET "NOTION_API_TOKEN"` (aliases `NOTION_TOKEN`, `NOTION_INTEGRATION_TOKEN`, `NOTION_ACCESS_TOKEN`). Never commit real credentials.
5. Share databases/pages with the connection via Notion **Add connections**.
6. Successful smoke: `GET /v1/users/me` with `Notion-Version: 2022-06-28` → **HTTP 200** with `id`. Invalid tokens → **HTTP 401**.

## Example payloads

**getUserMe (smoke):**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_NOTION_API_TOKEN"
}
```

**createPage (device-log row):**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "parent": { "database_id": "YOUR_DATABASE_ID" },
  "properties": {
    "Name": {
      "title": [{ "text": { "content": "Coreflux alarm — Zone A" } }]
    }
  }
}
```

**updatePage:**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "page_id": "YOUR_PAGE_ID",
  "properties": {
    "Status": { "select": { "name": "Acknowledged" } }
  }
}
```

**queryDatabase:**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "database_id": "YOUR_DATABASE_ID",
  "page_size": 10
}
```

## Deploy notes

* Deploy `NotionRestApi.lot` only (no `ADD METADATA`).
* Hub catalog metadata lives in `hub-metadata.lot` (`WITH STATUS "beta"`, icon, doclink).
* Docs: [https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/notion](https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/notion)

## Sources

* [Notion API introduction](https://developers.notion.com/reference/intro)
* [Create a page](https://developers.notion.com/reference/create-a-page)
* [Update page](https://developers.notion.com/reference/patch-page)
* [Query a database](https://developers.notion.com/reference/post-database-query)
* [Retrieve a database](https://developers.notion.com/reference/retrieve-a-database)
* [Retrieve your token's bot user](https://developers.notion.com/reference/get-self)
* [Search](https://developers.notion.com/reference/post-search)
* [Versioning](https://developers.notion.com/reference/versioning)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.