Notion API for Beginners: Build Your First Integration

The Notion API lets your code read and write pages and databases, which means Notion can become the back-end of a custom app, a sync target for another tool, or a reporting source. This guide gets you from zero to your first working request.

Step 1: Create an integration

Go to your Notion integrations settings and create a new internal integration. Give it a name and pick the workspace. You will receive a secret token. Treat it like a password and store it in an environment variable, never in code that ships to a browser.

Step 2: Share a page with the integration

An integration can only see pages you explicitly share with it. Open a database page, click the share menu, and invite the integration by name. This is Notion's permission model for the API: explicit, per-page, revocable.

The easy mistake

People call the API, see an empty result, and assume the code is broken. Almost always the integration was never shared with the page. Share first.

Step 3: Make your first request

Fetch the database you shared. With curl:

```
curl -X GET 'https://api.notion.com/v1/databases/YOUR_DATABASE_ID/query' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Notion-Version: 2022-06-28'
```

The response is a JSON object with a results array of pages and their properties.

Step 4: Write data back

To add a row, POST to the same database's query endpoint is for reads. For writes, POST to https://api.notion.com/v1/pages with a parent pointing at the database and a properties object matching your column names and types.

Property types map to JSON shapes

A title is an array of text objects. A select is a string. A date is an object with a start. The mapping is the fiddly part; copy a working example and adjust rather than writing property payloads from memory.

Step 5: Choose a library

Raw HTTP works, but a client library saves time. Official SDKs exist for JavaScript and Python. Community libraries cover most other languages. A library handles the version header, pagination, and error retry so you can focus on the data.

Realistic use cases

• Sync a form tool into a Notion database so submissions appear as rows.
• Publish a daily report by reading rows created today and writing a summary page.
• Mirror an external tracker (GitHub issues, Linear tasks) into Notion for a single view.
• Back a simple internal app that reads and writes Notion as its database.

Limits to know

• The API rate-limits around three requests per second per integration. Batch where you can.
• Search across the whole workspace is limited; navigate from a known page or database instead.
• Webhooks are not native. For push-style updates, poll on a schedule or use an external automation tool.

Security basics

• Never expose the integration token in client-side code. Route requests through a server or serverless function.
• Scope the integration to the pages it needs, not the whole workspace.
• Rotate the token if it leaks; sharing is per-page so revoking access is instant.

When to use the API vs no-code

If you can solve a problem with native Notion automations or Zapier, do that first. Reach for the API when you need custom logic, scheduled jobs, or a real application front-end.

Templates that welcome the API

The store's templates use standard database structures and clear property names, so building an integration against them is straightforward rather than a reverse-engineering exercise.