Notion API

{
  "service_type": "platform",
  "base_url": "https://notion.com",
  "auth_method": "oauth2",
  "auth_config": {
    "authorization_url": "https://api.notion.com/v1/oauth/authorize",
    "token_url": "https://api.notion.com/v1/oauth/token",
    "scopes": [],
    "grant_types": [
      "authorization_code",
      "client_credentials"
    ],
    "notes": "Public integrations use OAuth 2.0 with client ID and secret. Internal integrations use an internal integration token (secret) passed as a Bearer token."
  },
  "endpoints": [
    {
      "name": "Search",
      "method": "POST",
      "path": "/v1/search",
      "description": "Search all pages and databases shared with the integration."
    },
    {
      "name": "Retrieve a database",
      "method": "GET",
      "path": "/v1/databases/{database_id}",
      "description": "Retrieve a database object by ID."
    },
    {
      "name": "Query a database",
      "method": "POST",
      "path": "/v1/databases/{database_id}/query",
      "description": "Query a database with filters and sorts."
    },
    {
      "name": "Create a database",
      "method": "POST",
      "path": "/v1/databases",
      "description": "Create a new database as a child of a page."
    },
    {
      "name": "Update a database",
      "method": "PATCH",
      "path": "/v1/databases/{database_id}",
      "description": "Update properties and metadata of a database."
    },
    {
      "name": "Retrieve a page",
      "method": "GET",
      "path": "/v1/pages/{page_id}",
      "description": "Retrieve a page object by ID."
    },
    {
      "name": "Create a page",
      "method": "POST",
      "path": "/v1/pages",
      "description": "Create a page in a parent page or database."
    },
    {
      "name": "Update a page",
      "method": "PATCH",
      "path": "/v1/pages/{page_id}",
      "description": "Update page properties or archive/restore the page."
    },
    {
      "name": "Retrieve block children",
      "method": "GET",
      "path": "/v1/blocks/{block_id}/children",
      "description": "Retrieve child blocks of a block or page."
    },
    {
      "name": "Append block children",
      "method": "PATCH",
      "path": "/v1/blocks/{block_id}/children",
      "description": "Append child blocks to a parent block."
    },
    {
      "name": "Retrieve a user",
      "method": "GET",
      "path": "/v1/users/{user_id}",
      "description": "Retrieve a user object."
    },
    {
      "name": "List users",
      "method": "GET",
      "path": "/v1/users",
      "description": "List all users in the workspace."
    },
    {
      "name": "Retrieve comments",
      "method": "GET",
      "path": "/v1/comments",
      "description": "Retrieve comments on a page or block."
    },
    {
      "name": "Create a comment",
      "method": "POST",
      "path": "/v1/comments",
      "description": "Create a comment on a page."
    }
  ],
  "pricing_model": {
    "type": "freemium",
    "details": {
      "free_plan": "Free plan available for individuals and small teams with limited blocks, file uploads, and guest features.",
      "plus_plan": "Paid per-user plan with unlimited blocks, version history, and larger file uploads.",
      "business_plan": "Higher-tier per-user plan with advanced admin, audit log, and SAML SSO.",
      "enterprise_plan": "Custom pricing with advanced security, compliance, and support.",
      "ai_addon": "Notion AI is available as a paid add-on.",
      "api_access": "API access is generally available on paid plans; free plan limitations may apply."
    }
  },
  "rate_limits": {
    "requests_per_second": 3,
    "notes": "Average rate limit is around 3 requests per second per integration. Notion may return 429 with Retry-After header. Specific limits can vary by endpoint and plan."
  },
  "capabilities": [
    "Workspace and knowledge management",
    "Documents, notes, and wikis",
    "Project and task management",
    "Relational databases with customizable properties",
    "Block-based content model for pages and nested structures",
    "OAuth 2.0 and internal integration tokens",
    "Search across shared pages and databases",
    "Read and write pages, databases, blocks, and users",
    "Comments API",
    "File uploads via external URLs or S3-compatible endpoints",
    "Webhooks for change notifications",
    "Notion AI writing and analysis features",
    "Calendar integration",
    "Forms and charts",
    "Automations and workflow triggers",
    "Integrations with third-party tools and services",
    "Enterprise search connectors",
    "Public API with SDKs for JavaScript and Python",
    "Notion Sites for publishing",
    "Template gallery and community templates",
    "Mobile, desktop, and web clients",
    "Web Clipper browser extension"
  ],
  "raw_analysis": "Notion is a mature, widely adopted collaboration and productivity platform with over 50 million users. It combines documents, wikis, databases, project management, and AI into a sing

3/3 tests passed

{
  "overall": 82,
  "dimensions": {
    "token_efficiency": 9.0,
    "first_try_success": 8.0,
    "response_parseability": 9.0,
    "error_clarity": 7.5,
    "doc_quality": 9.0,
    "auth_simplicity": 8.0,
    "latency": 9.5,
    "consistency": 9.0
  },
  "pricing_normalized": {
    "free_tier": true,
    "api_access_on_free": "limited",
    "paid_tiers": ["Plus", "Business", "Enterprise"],
    "ai_addon_cost": "paid add-on",
    "cost_per_seat_model": true
  },
  "issues": [
    "OAuth 2.0 setup requires registering an integration and managing tokens; not a passive/simple auth flow",
    "API access is effectively gated behind paid plans; free plan limitations are vaguely defined ('may apply')",
    "Notion AI is a separate paid add-on, adding cost ambiguity for AI-assisted workflows",
    "Block-based data model has a learning curve for agents writing structured content vs flat tables",
    "Webhook and file upload flows add integration complexity for full automation",
    "robots.txt blocks several paths, which may limit some automated content fetching scenarios"
  ],
  "recommendations": [
    "Surface a clear, concise value prop in llms.txt for agent onboarding (already strong — keep it up to date)",
    "Prefer 'Sign in with Notlogin' or magic-link OAuth to remove human-in-the-loop friction for agents",
    "Document exact free vs paid API limits with concrete numbers in developer docs",
    "Provide canonical JSON schema/examples for pages, blocks, and databases to reduce trial-and-error",
    "Publish an explicit status page and error-code reference to improve error clarity",
    "Offer a lightweight sandbox workspace for agents to test integrations without upgrading"
  ]
}