Notion REST API and web client cache coherence after property updates

Direct Answers

1. Token-scoped invalidation: A successful PATCH invalidates the cached GET representation only for the token that performed the write. Other tokens (including other integrations and personal tokens) may continue to serve stale data until their local cache expires.
2. Observable staleness window: Under typical load the web client UI and a fresh GET from a different integration diverge for a few seconds up to roughly 30 seconds. No official SLA or maximum staleness guarantee exists.
3. No forced-refresh mechanism: The API returns no Cache-Control headers, and no undocumented headers or query parameters (such as ?refresh=true) have been discovered that force revalidation. Consistency relies entirely on Notion’s internal eventual‑consistency propagation.

Confirmed vs. Likely Behavior

Confirmed: Notion’s API (version 2022-06-28) does not expose cache‑control headers, webhook delivery is best‑effort, and rate limits cap polling at three requests per second per integration. The documentation only acknowledges eventual consistency.

Likely explanation: The write path invalidates the cache entry associated with the requesting token. Other tokens hold independent cached representations that expire on their own timeline. This token‑scoped invalidation matches the observed pattern where the writing integration sees the change immediately while other consumers see a delay.

Verification Steps

1. Using integration token A, PATCH a page property (e.g., curl -X PATCH ... -H "Authorization: Bearer $TOKEN_A" -d '{"properties":{"Status":{"select":{"name":"Done"}}}}').
2. Immediately GET the same page with token A and confirm the property reflects the change.
3. Within the same second, GET the page with a different token B (or a personal token). Compare the property value to detect staleness.
4. Observe the Notion web client UI after the PATCH; note the time until the updated property appears. Compare with the API GET latency from token B to estimate the observable staleness window.

Practical Recommendations

• Design integrations to tolerate stale reads: treat GET responses as potentially outdated and rely on webhooks for near‑real‑time notification.
• Because webhooks are best‑effort and polling is rate‑limited, implement exponential back‑off and idempotent processing for rapid successive updates.
• If your workflow requires strong read‑after‑write consistency across tokens, consider a short application‑level delay (e.g., 5–10 seconds) before reading with a different token, or re‑read with the writing token when possible.

Missing Diagnostic Detail

What is the typical volume of concurrent property updates per page in your use case? High write throughput may widen the staleness window and affect the back‑off strategy.