Notion-Version Header for AI Agents: Pin API Versions Before Writes

To set Notion-Version for an AI-agent workflow, choose an explicit API date, build the request for that contract, and keep the selection fixed through review and dispatch. Do not let the agent silently change the version to make a failed write pass. The header selects API behavior; it does not grant page access or prove the proposed change is correct.

ActionDock puts this choice in the owner’s connection settings. Its current implementation accepts 2025-09-03 or 2026-03-11, sends the selected header on compatible Notion REST reads and writes, and includes it in the exact write-approval preview. There is no automatic default or upgrade.

What the Notion-Version header controls

Notion requires Notion-Version on REST API requests. Its date-based versions identify backwards-incompatible API contracts. For example, the provider-facing header for a request written against the March 2026 contract is:

Notion-Version: 2026-03-11

Notion’s versioning documentation also explains an important limit: pinning a version does not freeze every behavior. Additive response fields, rate limits, link formats, and opaque cursor formats can still change. Keep response handling tolerant of additions and use documented record IDs instead of extracting identifiers from human-facing URLs.

For an agent, the practical rule is simple: select the contract before constructing the write, not after receiving an error. That is a workflow recommendation, not a claim that a header makes arbitrary agent output safe.

Three different meanings of version

These controls are not interchangeable. ActionDock’s ETag and If-Match guide covers conditional writes only when the target API enforces them. Do not infer that a Notion page endpoint supports conditional writes merely because ActionDock accepts ifMatch for compatible providers.

A concrete reason not to swap versions blindly

The Notion 2026-03-11 upgrade guide describes three breaking changes from 2025-09-03: block positioning changes from after to a position object, the old archived field becomes in_trash, and the transcription block type becomes meeting_notes.

A migration therefore involves request bodies and response handling—not just replacing a date. In particular, the old field is archived, not is_archived; do not rename similarly spelled fields without checking their documented meaning. The workflow below changes only a page title, not trash or archive state.

Configure a narrow page-update workflow in ActionDock

Use a disposable page you control first. The following is a configuration and payload example, not a report of a live Notion-account test. The approved integrations overview explains the gateway boundary.

1. Choose the version and provider permissions

Prepare a Notion bearer token with access to the target page. Read and update permissions are separate: Notion’s connection capabilities distinguish Read content from Update content. A successful GET does not establish that PATCH is permitted.

In Connections, configure:

• Base URL: https://api.notion.com/v1/
• Authentication: bearer, with the credential stored in the connection rather than the prompt
• Notion API version: the supported date your request expects
• Policy mode: Manual allowlist
• Methods: GET and PATCH
• Allowed path prefix: /pages/<page-id>, using the real page ID rather than a broad /pages/ or / prefix

The page scope is a path prefix, not an exact-URL-only lock. Review any descendant routes it permits. The two version dates above are ActionDock’s accepted choices, not a claim that they are the only versions Notion supports.

2. Read the intended page

Open Test GET, enter /pages/<page-id>, and choose Run GET. Inspect the saved provider response, including its HTTP status and body. Refresh result rereads the same job; it does not issue another provider request. See the specific-resource check contract.

Notion’s retrieve-page endpoint returns page properties, not the page’s full block content. Confirm the page ID and the title property you intend to change. Do not mistake a successful metadata read for a complete content review.

3. Propose one minimal PATCH

This illustrative integration.execute input assumes a page in a data source whose title property is named Name. Replace both identifiers and use the real property name or ID from that page’s schema. The update-page contract requires matching property identifiers; for a page outside a data source, only its title property can be changed through properties.

{
  "connectionId": "<owner-configured connection UUID>",
  "method": "PATCH",
  "path": "/pages/<page-id>",
  "body": {
    "properties": {
      "Name": {
        "title": [
          { "text": { "content": "Release checklist - reviewed" } }
        ]
      }
    }
  }
}

There is deliberately no headers or apiVersion field in the action input. The agent cannot override the owner’s selected version. MCP list_connections exposes the selection so the caller can prepare a compatible request without receiving the stored credential.

4. Review the version with the body

The write waits for the signed-in workspace owner. The exact preview includes the destination, method, path, query, body, connection revision, and a field shaped like:

{
  "versionHeader": {
    "name": "Notion-Version",
    "value": "2026-03-11"
  }
}

Approve only when the version, target and proposed title all match the intended change. An agent API key cannot approve its own write. The human-in-the-loop approval guide explains this separation.

After execution, inspect the provider receipt and deliberately read the page again if you need evidence of its current title. ActionDock records what it observed; its receipt is not independent attestation of the provider’s resulting state.

Upgrade a connection without reusing old approval

Treat a version upgrade as a reviewed configuration change:

1. Read the provider’s migration guide and update request construction and response parsing together.
2. Test the new contract against disposable data before proposing a production change. The API-write testing guide gives a broader checklist.
3. Have the owner save the new Notion API version in the connection.
4. Submit a fresh proposal with a new idempotency key and obtain separate owner approval.

Every saved connection edit increments its revision. Earlier proposals become stale, and queued approvals cannot authorize a write using the changed configuration. ActionDock checks the approval snapshot and rechecks the connection revision before write dispatch. This does not cancel a request that has already passed that final check.

Legacy Notion connections with no selected version remain listable and editable, but reads, writes and Test GET are blocked before dispatch until the owner configures one. For owner API updates, omitting apiVersion preserves the stored choice; moving to another provider host requires explicitly clearing it with null. The API-version contract documents these settings.

Boundaries to keep in the workflow

Pinning does not validate arbitrary JSON against Notion’s schema, translate old payloads, grant permissions, or guarantee a business outcome. ActionDock does not add Notion OAuth setup, beta headers, native Notion MCP, file uploads, credential refresh or automatic provider retries. Its version-header transport tests use mocks, not a live Notion account.

If a write becomes execution_unknown, reconcile the external state before considering a replacement; changing the API date is not a recovery procedure. Follow the retry and idempotency guide, keeping the original evidence intact.

Finally, the gateway controls only requests routed through ActionDock’s MCP or HTTP API. Direct provider credentials, browser sessions and native Notion tools remain outside that boundary. A useful version pin belongs inside a reviewed request path—not alongside an uncontrolled alternative route.