Carapace
All Guides
Productivity

Notion

Manage pages, databases, and blocks

Notion Setup Guide

Enables your agent to read, create, and update pages, query and manage databases, search content, and post comments in Notion.

Prerequisites

  • A Notion account with access to the workspace you want the agent to use

Step 1: Create an Internal Integration

  1. Go to notion.so/my-integrations
  2. Click New integration
  3. Fill in:
    • Name: e.g., "Carapace Agent"
    • Associated workspace: select the workspace the agent should access
    • Type: keep as "Internal"
  4. Under Capabilities, ensure these are enabled:
    • Read content
    • Update content
    • Insert content
    • Optionally: Read comments, Create comments if the agent needs comment access
  5. Click Save changes
  6. Copy the Internal Integration Secret (starts with ntn_ or secret_)

Step 2: Share Pages and Databases with the Integration

This is the most commonly missed step. The integration cannot access any content until you explicitly share it.

For every page or database the agent should access:

  1. Open the page in Notion
  2. Click the ... menu (top right)
  3. Click Connections (or Add connections)
  4. Search for your integration name (e.g., "Carapace Agent")
  5. Click to connect it

Repeat for each page or database. Sharing a parent page does NOT automatically share its children — you must share each resource individually, or share a top-level page and choose "Include sub-pages" when prompted.

Step 3: Connect in Carapace

  1. Go to Dashboard > Connections
  2. Find Notion and click Connect
  3. Paste the integration token in the API Key field
  4. Click Save Credentials

Credential Fields Reference

FieldRequiredFormatDescription
api_keyYesStarts with ntn_ or secret_Internal Integration Token

Gotchas

You must share content with the integration: This is the #1 support issue. Creating the integration alone does not grant access to any pages. You must explicitly connect the integration to each page or database via the Notion UI. If the agent returns empty results, this is almost certainly the cause.

Parent sharing does not cascade automatically: When you share a parent page, Notion may prompt you to "Include sub-pages." If you skip this, child pages remain inaccessible. When adding new child pages later, you may need to re-share.

Token format change: Older integrations use tokens starting with secret_. Newer ones start with ntn_. Both formats are valid and work identically.

Workspace-specific: Each integration token is tied to one workspace. If you need the agent to access multiple workspaces, create a separate integration in each and connect them individually in Carapace.

Rate limits: Notion's API enforces rate limits (currently 3 requests per second per integration). High-frequency agent operations may hit these limits, resulting in 429 responses.

Troubleshooting

Agent returns empty results for pages that exist

The integration hasn't been shared with those pages. Follow Step 2 for each page.

"Object not found" errors

The integration doesn't have access to the specific page or database ID. Verify it's connected via the page's ... > Connections menu.

401 Unauthorized

The integration token is invalid or was regenerated. Copy the current token from notion.so/my-integrations and update it in the Carapace dashboard.

See Also