# Notion — API Agent Score

> Score: 87/100 (Grade: A) | Domain: notion.com | Rubric: 1.0.0 | Checked: July 24, 2026

Notion scored 87/100 (A), classified "ai-ready".

[View full report](https://www.postman.com/ai/ai-ready-apis/company/notion)
[All organizations](https://www.postman.com/ai/ai-ready-apis/llms.txt)

## Summary

- Overall: 87/100 (A)
- Classification: ai-ready

## Category Scores

- API Design: 100/100 (A+)
- Developer Experience: 75/100 (B)
- Agent Discovery: 97/100 (A+)
- Agent Understanding: 81/100 (A)
- Agent Usability: 84/100 (A)

## Check Results

### API Design

- [pass] Machine-readable, versioned contract — Versioning declared (info.version="2.0.0") and header-versioning detected. Investigated: spec 100%, docs 100%.
- [pass] Schema coverage & depth — 26/26 (100%) public params are fully typed (no any/**kwargs). Analyzer confirms all methods have a derivable input schema. Investigated: sdk 100%, spec 67%.
- [pass] Auth declared & discoverable — Authentication required (global or on every operation). Investigated: spec 100%, docs 100%.
- [pass] Security & governance hygiene — No credential-shaped strings detected in spec. Investigated: spec 100%, wellknown 50%.
- [pass] Example coverage — README is present and includes a runnable quickstart. Investigated: sdk 100%, spec 0%, docs 0%.

### Developer Experience

- [pass] Self-service developer portal — Signup page at https://app.notion.com/signup; no free-tier language detected in docs/pricing. Investigated: docs 100%.
- [pass] Description completeness — 74% description completeness (target 90%+). Investigated: spec 100%, sdk 100%.
- [pass] Changelog published — Newest official SDK activity 0 day(s) ago. Investigated: sdk 100%, spec 0%, docs 0%.
- [warn] Quickstart present — Quickstart page reachable (1 variants scanned starting at https://developers.notion.com/guides/get-started/overview) but no runnable code sample detected in HTML or .md variant. Investigated: docs 50%.
- [fail] Code samples in docs — No detectable code samples across 20 sampled docs pages. Investigated: docs 0%.

### Agent Discovery

- [pass] Docs reachable, not hard auth-gated — All 50 sampled pages are publicly accessible. Investigated: docs 100%.
- [pass] Registry & SDK presence — Indexed on Context7 (websites/notion_help, 4135 snippets). Investigated: docs 100%, sdk 100%, cli 100%, mcp 100%, wellknown 0%.
- [warn] llms.txt present, valid & comprehensive — llms.txt contains parseable links but doesn't fully follow the proposed structure: https://developers.notion.com/llms.txt: No blockquote summary found. Investigated: docs 88%, sdk 0%.
- [pass] Crawlable / AEO — Docs paths crawlable by all monitored AI agents. Investigated: wellknown 100%.

### Agent Understanding

- [pass] Machine-readable errors (RFC 9457) — 5 distinct 4xx/5xx response codes documented. Investigated: docs 100%, spec 50%, sdk 0%.
- [pass] Operation purpose clarity — 100% of operations have a clear summary + operationId an agent can select on. Investigated: spec 100%.
- [warn] Agent-navigable, token-efficient docs — 4 of 49 pages have substantive content differences between markdown and HTML (avg 4% missing). Investigated: docs 67%.
- [pass] Docs structured data — JSON-LD Article markup on 20/20 assessed pages (100%) with dateModified present. Investigated: docs 100%.
- [warn] Description consistency across surfaces — Mean pairwise description similarity across 3 surfaces (spec, docs, sdk) is 8% (threshold 35% for full credit).
- [fail] Agent instructions file (AGENTS.md) — No AGENTS.md at the site root or /.well-known/. Investigated: wellknown 0%.

### Agent Usability

- [pass] Idempotency documented — Built-in retry machinery is present (grep-derived). Investigated: sdk 100%, spec 0%, docs 0%.
- [pass] Rate-limit signaling — rate-limit behavior documented in the docs site at https://developers.notion.com/reference/request-limits. Investigated: spec 100%, docs 100%.
- [pass] Sandbox separation — Sandbox environments are exposed (sandbox). Investigated: sdk 100%, spec 0%, docs 0%.
- [warn] Pagination documented & consistent — Only 2/6 list method(s) return an auto-paginating iterable; 4 return a raw page. Investigated: sdk 33%.
- [warn] Runnable collection with test scripts — No test scripts found in the workspace's collections. Investigated: platform 50%.

## Executive Summary

Notion's API program shows strong fundamentals in discovery and documentation parseability, but two gaps put partner and agent adoption at risk: AI agents lack the structured instruction context they need to reliably work with the API, and partners arriving at the docs don't have inline code samples to accelerate their first successful call. Closing the agent-context gap first will meaningfully improve how every AI-powered integration tool — and the developers using them — understands and acts on Notion's API surface. Pairing that with runnable, always-current code samples in the docs will compress the time from discovery to a working integration.