Skip to content
Docs
Docs & knowledge

Notion

Let hires search and read your Notion pages, work through databases, add pages, keep pages up to date and comment.

Explore 7 actions and their permissionsExact inputs, sign-in scopes, access limits and approval rules.

With Notion, a hire can:

  • search pages and databases by their titles, or see what changed most recently,
  • read a page as plain text (headings, lists, to-dos and tables), with its open comments,
  • go through a database's rows, filtered and sorted the way you'd set up a view,
  • add a page to a database, with its properties filled in and some text,
  • add text to the end of a page, leaving what's there as it is,
  • change a page's properties, like a task's status or due date, or its title,
  • comment on a page.

1. Choose how Roster signs in

  • An internal integration (quickest). In Notion's developer portal (the form in Roster links there too), under Internal connections, click Create a new connection, name it Roster and choose your workspace. Copy the API token from its Configuration tab (it starts with ntn_, or secret_ for older ones). Under Capabilities, allow reading, updating and inserting content, and reading and inserting comments.
  • A public integration of yours (OAuth). Make a Public integration on the same page, set its redirect URI to the address Roster shows on the connection (it ends in /api/integrations/notion/oauth/callback), and copy its client ID and secret. When you connect, Notion asks which pages to share.

What hires write shows in Notion as the integration, by its name.

2. Share pages with it

Notion only lets an integration see what's shared with it. With an internal integration, open each top-level page or database hires should work in, click ••• → Connections, and add your integration. Everything under a shared page is shared too.

3. Connect it in Roster

  1. Open Integrations → Tools → Add a tool, search for Notion and choose it.
  2. How Roster signs in: pick the way you chose above. Only its fields are shown.
  3. Paste the internal integration secret, or the public integration's client ID and secret.
  4. Click Connect. With an internal integration, Roster checks the secret with Notion, and the connection shows Connected as your Notion workspace. If Notion refuses it, Roster says so and saves nothing. With a public integration, then click Connect with Notion and choose the pages to share.

4. Give hires access

On the hire's Tools tab, click Give access on Notion:

  • Read only: it can search, read pages and go through databases, and nothing else.
  • Read and write: it can also add pages, add to pages, change properties and comment.
  • Root pages: links to pages, one per line. The hire then only works in those pages and what's under them (sub-pages and databases included), even if more is shared with Roster. Leave it empty for everything shared.

Hires refer to pages and databases by their link or id, and to properties and options by the names you see in Notion, so "set Status to Done" works the way your team says it.

Watching for changes

A hire's responsibility can watch Notion: when pages it can use are edited, the hire is woken with the list. Checking is one search and costs nothing when nothing changed.

If something goes wrong

  • "Couldn't find that": the page or database isn't shared with the integration. Add it under ••• → Connections.
  • "Outside the pages it works in": it's not under the hire's root pages. Add its top page to the list, or leave the list empty.
  • "Is a people property, which hires can't set": some properties (people, files, formulas) can't be set by a hire yet; change those in Notion.

Tools and permissions reference

This reference is built from the same definitions Roster uses to connect Notion and give hires access. It updates with each release.

Authentication and requested permissions

The account or app you connect sets the outer limit. Each hire's access can narrow it further. Connecting a tool gives it to no hire until you give access on that hire's Tools tab.

API key or access token

At notion.so/profile/integrations: New integration (internal), then copy its secret. Share pages with it in Notion (••• → Connections).

For: How Roster signs in: Internal integration secret.

OAuth 2.0

From the public integration you made at notion.so/profile/integrations.

For: How Roster signs in: An OAuth app of yours.

When making a key, use these permissions from the connection guide:

  • Read content
  • Update content
  • Insert content
  • Read comments
  • Insert comments

Connection fields

Notion connection fields
FieldWhat to provide
How Roster signs in
signIn
Optional		An internal integration is quickest: you share pages with it in Notion. A public OAuth app lets people pick pages when they connect.

Choices: Internal integration secret (token); An OAuth app of yours (oauth).

Starts with: token.

Internal integration secret
token
Required · sealed secret		At notion.so/profile/integrations: New integration (internal), then copy its secret. Share pages with it in Notion (••• → Connections).

Shown when signIn: token.

OAuth app client ID
clientId
Optional		From the public integration you made at notion.so/profile/integrations.

Shown when signIn: oauth.

OAuth app client secret
clientSecret
Optional · sealed secret		Use the value for your account or connection.

Shown when signIn: oauth.

Per-hire limits

Read-only hires receive only actions that read. Read-and-write access also allows actions that change things, where the connection itself permits them. An empty resource allowlist usually means everything the connected account can reach; each field below explains its meaning.

Notion per-hire limits
FieldWhat to provide
Root pages
roots
Optional		Links to pages, one per line: the hire only works in them and what's under them. Leave empty for everything shared with Roster in Notion.

Actions

7 actions: 3 only read and 4 change something. A read action may still need approval when your workspace or hire is set to ask. A locked approval requirement always applies.

7 of 7 actions. Open an action for its arguments and full input schema.

searchRead only

Find pages and databases by words in their titles, most relevant first; with no words, the most recently edited.

Approval: Uses your workspace and hire approval settings.

Arguments for search
ArgumentTypeDetails
queryOptionalstringSee input schema below.Default: ""
kindOptional"any" | "page" | "database"See input schema below.Default: "any"
limitOptionalintegerSee input schema below.Default: 10
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "query": {
      "default": "",
      "type": "string"
    },
    "kind": {
      "default": "any",
      "type": "string",
      "enum": [
        "any",
        "page",
        "database"
      ]
    },
    "limit": {
      "default": 10,
      "type": "integer",
      "minimum": 1,
      "maximum": 25
    }
  }
}
read_pageRead only

A page's properties and text (headings, lists, to-dos, tables as plain text) and its open comments.

Approval: Uses your workspace and hire approval settings.

Arguments for read_page
ArgumentTypeDetails
pageRequiredstringthe page's link or id
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "page": {
      "type": "string",
      "minLength": 1,
      "description": "the page's link or id"
    }
  },
  "required": [
    "page"
  ]
}
query_databaseRead only

Rows of a database, optionally filtered and sorted. `filter` is a Notion filter object, e.g. {"property":"Status","status":{"equals":"Done"}} or {"and":[…]}; `text` matches the title.

Approval: Uses your workspace and hire approval settings.

Arguments for query_database
ArgumentTypeDetails
databaseRequiredstringthe database's link or id (or a data source id)
textOptionalstringonly rows whose title contains this
filterOptionalobjecta Notion filter object
sort_byOptionalstringa property name, or "last_edited_time"
directionOptional"ascending" | "descending"See input schema below.Default: "descending"
limitOptionalintegerSee input schema below.Default: 25
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "database": {
      "type": "string",
      "minLength": 1,
      "description": "the database's link or id (or a data source id)"
    },
    "text": {
      "description": "only rows whose title contains this",
      "type": "string"
    },
    "filter": {
      "description": "a Notion filter object",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "sort_by": {
      "description": "a property name, or \"last_edited_time\"",
      "type": "string"
    },
    "direction": {
      "default": "descending",
      "type": "string",
      "enum": [
        "ascending",
        "descending"
      ]
    },
    "limit": {
      "default": 25,
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "database"
  ]
}
create_pageRead and write

Add a page (a row) to a database, with its title, properties and optional text. Property names are the database's own.

Approval: Uses your workspace and hire approval settings.

Arguments for create_page
ArgumentTypeDetails
databaseRequiredstringthe database's link or id
titleRequiredstringSee input schema below.
propertiesOptionalobjectproperty name → value: text, a number, true/false, a date like 2026-11-30, or option names (a list or "a, b")Default: {}
contentOptionalstringthe page's text; # headings, - bullets and [ ] to-dos workDefault: ""
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "database": {
      "type": "string",
      "minLength": 1,
      "description": "the database's link or id"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2000
    },
    "properties": {
      "default": {},
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "number"
          },
          {
            "type": "boolean"
          },
          {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        ]
      },
      "description": "property name → value: text, a number, true/false, a date like 2026-11-30, or option names (a list or \"a, b\")"
    },
    "content": {
      "default": "",
      "description": "the page's text; # headings, - bullets and [ ] to-dos work",
      "type": "string"
    }
  },
  "required": [
    "database",
    "title"
  ]
}
append_to_pageRead and write

Add text to the end of a page, keeping what's there. # headings, - bullets, 1. numbers, [ ] to-dos, > quotes and ``` code work.

Approval: Uses your workspace and hire approval settings.

Arguments for append_to_page
ArgumentTypeDetails
pageRequiredstringthe page's link or id
textRequiredstringSee input schema below.
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "page": {
      "type": "string",
      "minLength": 1,
      "description": "the page's link or id"
    },
    "text": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "page",
    "text"
  ]
}
update_pageRead and write

Change a page's properties (a database row's status, dates, owner fields…) or its title. Only what's given changes.

Approval: Uses your workspace and hire approval settings.

Arguments for update_page
ArgumentTypeDetails
pageRequiredstringthe page's link or id
titleOptionalstringSee input schema below.
propertiesOptionalobjectproperty name → value: text, a number, true/false, a date like 2026-11-30, or option names (a list or "a, b")
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "page": {
      "type": "string",
      "minLength": 1,
      "description": "the page's link or id"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2000
    },
    "properties": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "number"
          },
          {
            "type": "boolean"
          },
          {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        ]
      },
      "description": "property name → value: text, a number, true/false, a date like 2026-11-30, or option names (a list or \"a, b\")"
    }
  },
  "required": [
    "page"
  ]
}
commentRead and write

Comment on a page.

Approval: Uses your workspace and hire approval settings.

Arguments for comment
ArgumentTypeDetails
pageRequiredstringthe page's link or id
textRequiredstringSee input schema below.
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "page": {
      "type": "string",
      "minLength": 1,
      "description": "the page's link or id"
    },
    "text": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "page",
    "text"
  ]
}

Watches and incoming events

  • This integration supports a responsibility that watches for changes. The guide above explains what it checks and how to limit it.
  • No incoming webhook handler is declared for this integration.

Limits and troubleshooting

  • Permission errors: check both the connected account's rights and the hire's resource and read/write limits.
  • Expired or revoked access: reconnect or replace the key on the connection.
  • Rate limits and unavailable services can interrupt work. The hire's timecard records the outcome.
  • The action schema describes accepted inputs. It does not grant additional access or bypass approvals.

Service documentation · Integration source reference

NocoDB

Spreadsheet-style tables over your databases.

Outline

A fast team wiki: documents, collections and search.

On this page

1. Choose how Roster signs in2. Share pages with it3. Connect it in Roster4. Give hires accessIf something goes wrongTools and permissions reference