Notion API Updates 2026: Every Major Change So Far

Notion has shipped three API versions in 2026 so far: 2026-02-01, 2026-03-01, and 2026-04-01. Each release added capabilities that were previously only available through the Notion UI. This post covers every significant Notion API update in 2026, organized chronologically, with code examples and migration notes for each version.

Timeline of 2026 API Releases

| API Version | Release Date | Headline Feature | Breaking Changes | |---|---|---|---| | 2026-02-01 | February 3 | Bulk operations, formula property write support | Pagination default reduced to 50 | | 2026-03-01 | March 3 | Webhooks (initial release), comment threading | Webhook secret validation required | | 2026-04-01 | April 7 | Views API (8 endpoints), smart filters, new block types | Rate limit header format, pagination cursor format |

February 2026: Bulk Operations and Formula Writes

The 2026-02-01 API version introduced two features that significantly reduced the number of API calls needed for common integration patterns.

Bulk Page Operations

Before February 2026, updating multiple pages required one API call per page. The new bulk endpoints accept up to 100 pages in a single request:

# Update the status of 3 pages in one call
curl -X PATCH "https://api.notion.com/v1/pages/bulk" \
  -H "Authorization: Bearer $NOTION_TOKEN" \
  -H "Notion-Version: 2026-02-01" \
  -H "Content-Type: application/json" \
  -d '{
    "pages": [
      {
        "page_id": "page_id_1",
        "properties": {
          "Status": { "status": { "name": "Done" } }
        }
      },
      {
        "page_id": "page_id_2",
        "properties": {
          "Status": { "status": { "name": "Done" } }
        }
      },
      {
        "page_id": "page_id_3",
        "properties": {
          "Status": { "status": { "name": "Done" } }
        }
      }
    ]
  }'

The response returns the updated pages in the same order. If any individual page update fails (permissions, validation), the others still succeed, and the response includes an errors array alongside the results array.

Formula Property Write Support

Formula properties were previously read-only through the API. Starting with 2026-02-01, you can write to formula properties by setting the formula expression directly:

{
  "properties": {
    "Total Cost": {
      "formula": {
        "expression": "prop(\"Quantity\") * prop(\"Unit Price\")"
      }
    }
  }
}

This is useful for programmatically creating or updating database schemas where computed columns need formulas set during setup.

Pagination Default Change

The default page size for list and query endpoints dropped from 100 to 50. If your integration relied on the implicit default of 100 results, you need to explicitly pass "page_size": 100 to maintain the same behavior.

March 2026: Webhooks and Comment Threading

The 2026-03-01 release was the most anticipated of the year. Webhooks eliminated the need for polling, which was the top request on Notion's public feature tracker for three years.

Webhook System

The initial webhook implementation supports registering HTTPS endpoints that receive POST requests when pages or blocks change in a specified scope (database or workspace):

# Register a webhook for a database
curl -X POST "https://api.notion.com/v1/webhooks" \
  -H "Authorization: Bearer $NOTION_TOKEN" \
  -H "Notion-Version: 2026-03-01" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/notion-webhook",
    "scope": {
      "type": "database",
      "database_id": "your_database_id"
    },
    "events": ["page.created", "page.updated"]
  }'

Notion sends a verification challenge on registration (similar to Slack's URL verification). Your endpoint must respond with the challenge value within 3 seconds.

Webhook Payload Structure (March)

The initial March payload format did not include a top-level event_type field. Routing required inspecting nested data:

{
  "event_id": "evt_abc123",
  "timestamp": "2026-03-15T10:00:00.000Z",
  "data": {
    "object": "page",
    "action": "updated",
    "page_id": "page_xyz",
    "changes": {
      "properties": {
        "Status": {
          "old": { "status": { "name": "To Do" } },
          "new": { "status": { "name": "In Progress" } }
        }
      }
    }
  }
}

Comment Threading

The comments API added threading support. You can now reply to a specific comment by passing a parent_comment_id:

{
  "parent": { "page_id": "page_id" },
  "parent_comment_id": "comment_id",
  "rich_text": [
    { "text": { "content": "This is a threaded reply." } }
  ]
}

Threaded comments appear nested in the Notion UI. The GET /v1/comments endpoint returns a flat list with parent_comment_id references so you can reconstruct the tree client-side.

April 2026: Views API and Smart Filters

The 2026-04-01 release is the largest API update of the year so far. The Views API adds eight new endpoints, and several smaller improvements round out the release.

Views API Overview

Before April 2026, database views could only be configured through the Notion UI. The new Views API lets you create, read, update, and delete views programmatically:

| Method | Path | Description | |---|---|---| | GET | /v1/databases/{id}/views | List views on a database | | POST | /v1/databases/{id}/views | Create a new view | | GET | /v1/views/{id} | Retrieve a single view | | PATCH | /v1/views/{id} | Update a view | | DELETE | /v1/views/{id} | Delete a view | | POST | /v1/views/{id}/duplicate | Clone a view | | PATCH | /v1/views/{id}/properties | Configure visible columns | | POST | /v1/views/{id}/query | Query through a view |

The /v1/views/{id}/query endpoint is particularly useful. Instead of rebuilding a view's filter and sort logic in your integration code, you can query through the view directly and get the same results the user sees in the Notion UI.

Five view types are supported: table, board, timeline, calendar, and list. Gallery views are not yet available through the API.

Smart Filter Improvements

Two new filter operators arrived in April:

Relative date references let you filter by past_week, past_month, next_week, next_month, and this_week without computing timestamps in your integration:

{
  "filter": {
    "property": "Due Date",
    "date": { "this_week": {} }
  }
}

The "me" operator for people properties resolves to the authenticated user:

{
  "filter": {
    "property": "Assigned To",
    "people": { "contains": "me" }
  }
}

Rate Limit and Pagination Changes

Two infrastructure changes in April require attention during migration:

Rate limit headers switched from X-RateLimit-* prefixed format to RateLimit-* (following RFC 9110). The old headers are still returned but deprecated. The RateLimit-Reset value changed from a Unix timestamp to a delta in seconds.

Pagination cursors changed to opaque base64-encoded strings. Cursors from the old format still work with the new API version, but new-format cursors do not work with older API versions. Invalidate stored cursors when upgrading.

API Version Comparison

This table summarizes the key capability differences across the three 2026 API versions:

| Capability | 2026-02-01 | 2026-03-01 | 2026-04-01 | |---|---|---|---| | Bulk page updates | Yes (up to 100) | Yes | Yes | | Formula property writes | Yes | Yes | Yes | | Webhooks | No | Yes (basic) | Yes (with event_type) | | Comment threading | No | Yes | Yes | | Views API | No | No | Yes (8 endpoints) | | Relative date filters | No | No | Yes | | "me" operator | No | No | Yes | | Toggle heading blocks | No | No | Yes | | Synced block copy | No | No | Yes | | Archived page filter | No | No | Yes |

Migration Guide: Upgrading Across 2026 Versions

If you are upgrading from a pre-2026 API version, here is what to address for each release:

From any version to 2026-02-01

• Add explicit "page_size": 100 to any list/query calls that relied on the old default
• No other breaking changes

From 2026-02-01 to 2026-03-01

• If you register webhooks, your endpoint must handle the verification challenge (respond within 3 seconds)
• Webhook secrets are mandatory; validate the X-Notion-Signature header on every incoming request

From 2026-03-01 to 2026-04-01

• Switch rate limit header parsing from X-RateLimit-* to RateLimit-*
• Fix RateLimit-Reset parsing (now seconds delta, not Unix timestamp)
• Invalidate stored pagination cursors (new base64 format is not backward-compatible with older API versions)
• Update webhook handler to read event_type at the top level (optional but recommended)

What to Expect Next

Notion's public changelog and developer forum suggest several features are in active development for the second half of 2026:

• Gallery view API support: The Views API currently returns a 400 for gallery type. Forum posts from the Notion team indicate this is planned for a future release.
• Webhook filtering: The ability to subscribe to specific event types at registration time (currently you receive all events and filter server-side).
• Database template API: Creating and managing database templates programmatically.

These are not confirmed for specific API versions, but they appear frequently in the Notion developer community discussions.

Quick Reference: All New Endpoints in 2026

| Endpoint | API Version | Method | Description | |---|---|---|---| | /v1/pages/bulk | 2026-02-01 | PATCH | Bulk update up to 100 pages | | /v1/webhooks | 2026-03-01 | POST | Register a webhook | | /v1/webhooks | 2026-03-01 | GET | List webhooks | | /v1/webhooks/{id} | 2026-03-01 | GET | Retrieve a webhook | | /v1/webhooks/{id} | 2026-03-01 | DELETE | Delete a webhook | | /v1/databases/{id}/views | 2026-04-01 | GET | List views | | /v1/databases/{id}/views | 2026-04-01 | POST | Create view | | /v1/views/{id} | 2026-04-01 | GET | Retrieve view | | /v1/views/{id} | 2026-04-01 | PATCH | Update view | | /v1/views/{id} | 2026-04-01 | DELETE | Delete view | | /v1/views/{id}/duplicate | 2026-04-01 | POST | Clone view | | /v1/views/{id}/properties | 2026-04-01 | PATCH | Configure columns | | /v1/views/{id}/query | 2026-04-01 | POST | Query through view |

Fazm is an open source macOS AI agent. Open source on GitHub.