# Notion API Call

This task lets you interact with Notion (opens new window).

Added since v0.10.0

TIP

This feature requires installing notion-client:

$ pip install runflow[notion]

# Authentication

You can create an integration through https://www.notion.so/my-integrations (opens new window).

When a new integration is created, you should be able to obtain a new "Internal Integration Token". Click "Show" to display it.

screenshot of getting a new internal integration token

Additionally, you should share "Can Edit" permission for the parent page with the Integration you just created.

screenshot of sharing permission

# Example Usage: Update Page Title

  • Set client.auth with a Notion Integration Token.
  • Set api_method to pages.update.
  • Set page_id to the ID of the page. In case you're struggling with find the ID of the page, copy the page url, and you will have something like https://www.notion.so/soasme/Runflow-Test-ee5b6cd7a7a340d79ae5ae28c52b67ea. Turn the last bit of information ee5b6cd7a7a340d79ae5ae28c52b67ea into 8-4-4-4-12 form, e.g. ee5b6cd7-a7a3-40d7-9ae5-ae28c52b67ea.
  • Set properties. It's strongly recommended you read the Notion documentation Working with page content (opens new window) first. You will have a basic understanding of properties then.
flow "notion_update_title" {
  variable "notion_token" {
    default = ""
  }

  task "notion_api_call" "update_title" {
    client = {
      auth = var.notion_token
    }
    api_method = "pages.update"
    page_id = "ee5b6cd7-a7a3-40d7-9ae5-ae28c52b67ea"
    properties = {
      "title": {
        "id": "title",
        "type": "title",
        "title": [
          {
            "type": "text",
            "text": {
              "content": "Runflow Test"
            }
          }
        ]
      }
    }
  }
}
Click me to view the run output

Run

$ read -s RUNFLOW_VAR_notion_token
**********
$ export RUNFLOW_VAR_notion_token
$ runflow run examples/notion_update_title.hcl
[2021-07-12 22:14:43,328] "task.notion_api_call.update_title" is started.
[2021-07-12 22:14:44,358] "task.notion_api_call.update_title" is successful.

# Example Usage: Append Block Children

This example appends an H2 element "Runflow is awesome" to the page.

  • Set client.auth with a Notion Integration Token.
  • Set api_method to blocks.children.update.
  • Set block_id to the ID of the page. In case you're struggling with find the ID of the page, copy the page url, and you will have something like https://www.notion.so/soasme/Runflow-Test-ee5b6cd7a7a340d79ae5ae28c52b67ea. Turn the last bit of information ee5b6cd7a7a340d79ae5ae28c52b67ea into 8-4-4-4-12 form, e.g. ee5b6cd7-a7a3-40d7-9ae5-ae28c52b67ea.
  • Set children. It's strongly recommended you read the Notion documentation Working with page content (opens new window) first. You will have a basic understanding of properties then.
flow "notion_update_blocks" {
  variable "notion_token" {
    default = ""
  }

  task "notion_api_call" "append_blocks" {
    client = {
      auth = var.notion_token
    }
    api_method = "blocks.children.append"
    block_id = "ee5b6cd7-a7a3-40d7-9ae5-ae28c52b67ea"
    children = [
      {
        object = "block",
        type = "heading_2",
        heading_2 = {
          text = [
            {
              type = "text",
              text = {
                content = "Runflow is awesome",
              },
            },
          ],
        },
      }
    ]
  }
}

Click me to view the run output

Run

$ read -s RUNFLOW_VAR_notion_token
**********
$ export RUNFLOW_VAR_notion_token
runflow run examples/notion_update_blocks.hcl
[2021-07-12 22:53:32,327] "task.notion_api_call.update_blocks" is started.
[2021-07-12 22:53:33,315] "task.notion_api_call.update_blocks" is successful.

# Arguments Reference

  • api_method - (Required, str) The API methods. Choices include
    • "blocks.children.append"
    • "blocks.children.list"
    • "databases.list"
    • "databases.query"
    • "databases.retrieve"
    • "pages.list"
    • "pages.create"
    • "pages.retrieve"
    • "pages.update"
    • "users.retrieve"
    • "users.list"
    • "users.list"
    • "search"
  • The rest of arguments are the parameters for the api_method. For the full reference, please check https://developers.notion.com/reference/intro (opens new window). For example, when the api_method is pages.update (opens new window), the arguments include
    • page_id - (Required, str) The page ID.
    • properties - (Required, map) The page properties.
    • archived - (Optional, bool) Set to true to archive (delete) a page. Set to false to un-archive (restore) a page.
  • client - (Required, map) The client settings.
    • auth - (Required, string) The Notion integration token.
    • timeout_ms - (Optional, int) The timeout in ms. Default is 60_000ms.
    • base_url - (Optional, str) The notion base url. Default is "https://api.notion.com".
    • notion_version - (Optional, str) The notion API version.