notionapi-agent

Unofficial Node.js API client for Notion.so.

This is a work-in-progress project. If you need to use Notion's API in production, I recommend waiting for their official release.

Documentation

• Announcement
• Installation
• Quickstart
• Instance Options
• API Methods
• Note

Announcement

When using v0.6.0+, import this library with

const { NotionAgent } = require('notionapi-agent')

Instead of

const NotionAgent = require('notionapi-agent')

Installation

# Install latest release from NPM registry.
npm i notionapi-agent
# Install master branch of git repo from Github.
npm i dragonman225/notionapi-agent

Quickstart

An example script is included in the repository. See test/agent.spec.js. Or you can take a look at the below code block.

const fs = require('fs')
const { NotionAgent } = require('notionapi-agent')

/* Fill in your token. */
const options = {
  token: ''
}

const agent = new NotionAgent(options)

async function main() {
  try {
    /* Fill in a page id. */
    let pageId = ''
    let page = await agent.loadPageChunk(pageId)
    let assets = await agent.getAssetsJson()
    fs.writeFileSync(`PageChunk.json`, JSON.stringify(page.data), { encoding: 'utf-8' })
    fs.writeFileSync(`Assets.json`, JSON.stringify(assets.data), { encoding: 'utf-8' })
  } catch (error) {
    console.error(error)
  }
}

main()

The API requests are asynchronous and are implemented with Promise.

Instance Options

• token - (optional) The Notion API token to access your private pages. If you only need to access public pages, this can be empty. Follow this guide to obtain your token.
• timeZone - (optional) User's timezone, default: Asia/Taipei.
• locale - (optional) User's locale, default: en.
• suppressWarning - (optional) Whether to hide warnings, default: false.
• verbose - (optional) Whether to show status messages, default: true.

API Methods

All methods return Promise that will resolve with the following object :

{
  statusCode: Number // HTTP status code.
  data: Object // Object parsed from JSON response.
}

If raw response from Notion is not JSON, the data property will be an empty object.

loadPageChunk(pageID, chunkNo, cursor)

Execute a raw call to /api/v3/loadPageChunk

• pageID - (required, String) A page ID, dashed version.
• chunkNo - (optional, Number, default: 0)
• cursor - (optional, Object, default: { "stack": [] })

Returns :

{
  statusCode: Number // HTTP status code.
  data: Object // One chunk of the page.
}

getAssetsJson()

Execute a raw call to /api/v3/getAssetsJson

• (no parameter)

Returns :

{
  statusCode: Number // HTTP status code.
  data: Object // Paths to all assets like images, scripts, etc.
}

getRecordValues(requests)

Execute a raw call to /api/v3/getRecordValues

• requests - (required, Object) See below example.

  [
    {
      "table": "block",
      "id": "cbf2b645-xxxx-xxxx-xxxx-xxxxe8cfed93"
    }
  ]

Returns :

{
  statusCode: Number // HTTP status code.
  data: Object // Content of requested blocks, collection_views, etc.
}

loadUserContent()

Execute a raw call to /api/v3/loadUserContent

• (no parameter)

Returns :

{
  statusCode: Number // HTTP status code.
  data: Object // Everything about a user: identity information, settings.
}

queryCollection(collectionID, collectionViewID, aggregateQueries)

Execute a raw call to /api/v3/queryCollection

• collectionID - (required, String) A collection ID.

• collectionViewID - (required, String) A collectionView ID.

• aggregateQueries - (required, Object) See below example.

  [
    {
      "id":"count",
      "type":"title",
      "property":"title",
      "view_type":"table",
      "aggregation_type":"not_empty"
    }
  ]

Returns :

{
  statusCode: Number // HTTP status code.
  data: Object // Data in a collection.
}

submitTransaction(operations)

Execute a raw call to /api/v3/submitTransaction

• operations - (required, Object) The operations to submit. See below for example.

  [
    {
      "id":"cda54abd-xxxx-xxxx-xxxx-xxxx65c4a5e2",
      "table":"block",
      "path":["properties","title"],
      "command":"set",
      "args":[["test",[["h","yellow_background"]]]]
    }
  ]

Returns :

{
  statusCode: Number // HTTP status code.
  data: Object // Normally an empty object.
}

Note

Project Structure