Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.notion.com/llms.txt

Use this file to discover all available pages before exploring further.

Notion Workers are small Node/TypeScript programs that extend Notion. You write code, deploy it with the Notion CLI, and Notion hosts and runs it for you. No servers to manage. With Workers, you can: Workers are designed to be built with AI coding agents. Scaffold a project, describe what you want, and deploy.

​
What you can build

https://mintcdn.com/notion-demo/7WdlNb9IZkRhGCcR/icons/nds/arrowCircleLoopForward.svg?fit=max&auto=format&n=7WdlNb9IZkRhGCcR&q=85&s=25d8d1ea2405c9af06347df80ab90fcf

Sync data

Pull data from Salesforce, Stripe, GitHub, or any API into Notion databases — kept in sync automatically.
https://mintcdn.com/notion-demo/7WdlNb9IZkRhGCcR/icons/nds/aiFace.svg?fit=max&auto=format&n=7WdlNb9IZkRhGCcR&q=85&s=d473a8d294324c9f2e19f44d487744dd

Agent tools

Give Notion Custom Agents functions like “create a Jira ticket” or “look up a customer in our CRM.”

​
How it works

A worker is a single TypeScript file that exports a Worker instance. You register capabilities on it (like syncs or tools) and deploy with ntn workers deploy:
src/index.ts
import { Worker } from "@notionhq/workers";

const worker = new Worker();
export default worker;

// Register capabilities on the worker
worker.tool("sayHello", { /* ... */ });
worker.sync("customersSync", { /* ... */ });
Once deployed, Notion takes over:
  • Syncs run on a schedule (default every 30 minutes) and write results to Notion databases.
  • Tools appear in Notion Custom Agents and are called by agents on demand.
Your code runs in a sandboxed Node.js environment. You can make HTTP requests to external APIs, use secrets stored via the CLI, and authenticate with third-party services through OAuth.
ConceptWhat it does
WorkerThe container for your code. One worker per project.
CapabilitySomething the worker can do, i.e. a sync or tool. A worker can have one or more capabilities.
DatabaseA Notion database managed by a sync. You define its schema in code.
PacerRate-limits outbound API calls so you don’t hit third-party quotas.
OAuthHandles authorization flows for services like GitHub and Google.
SecretsEnvironment variables stored securely and injected at runtime.

​
Typical workflow

1

Scaffold a project

ntn workers new
This creates a new directory with a src/index.ts starter file, TypeScript config, and dependencies.
2

Write your capabilities

Add syncs or tools to src/index.ts. Use an AI coding agent to help. The template includes prompts and skills, like the /sync skill.
3

Deploy

ntn workers deploy
The CLI bundles your code, uploads it to Notion, and starts running your capabilities.
4

Iterate

Edit your code and redeploy.

​
Next steps

https://mintcdn.com/notion-demo/yKfkO8UsVZTLLPNp/icons/nds/arrowChevronDoubleForward.svg?fit=max&auto=format&n=yKfkO8UsVZTLLPNp&q=85&s=e9dad4152e1d3bf11e6a8404d9504665

Quickstart

Create and deploy your first worker in less than five minutes.
https://mintcdn.com/notion-demo/7WdlNb9IZkRhGCcR/icons/nds/terminal.svg?fit=max&auto=format&n=7WdlNb9IZkRhGCcR&q=85&s=ed75fe4bd49b0ec0117eeead6adb4e5d

CLI reference

Install and configure the Notion CLI.