Notion Integrations

Fetching Notion Integration Details

To retrieve detailed information about a specific Notion integration, including its configuration, dataset association, and sync settings, you can use the fetch endpoint. This operation allows you to inspect the current state of a Notion integration and verify its configuration before making updates or managing its lifecycle.

The fetch operation returns comprehensive information about the Notion integration including the linked dataset, synchronization schedule, token status (returned as masked for security), and record expiration settings. This is particularly useful when you need to audit integration configurations, troubleshoot sync issues, or prepare for updates to integration parameters.

The response includes all configuration details:

Security Note: The Notion API token is always returned as ******** (masked) in fetch responses to protect sensitive credentials. The actual token value is never exposed through the API after initial configuration. If the token field is null, it indicates that no token has been configured for this integration.

Important: The syncSchedule field determines how often the integration automatically synchronizes content from Notion. Common values include @daily, @hourly, and @weekly. The expiresIn field specifies the time in milliseconds after which imported records are considered stale and may be re-synced.

Updating Notion Integration Configuration

To modify the configuration of an existing Notion integration, including changing the target dataset, updating API credentials, adjusting sync schedules, or modifying content expiration policies, use the update endpoint. This operation enables you to adapt your Notion integration as your requirements evolve, such as redirecting content to different datasets, increasing sync frequency for time-sensitive content, or updating authentication tokens when they are rotated.

Updating a Notion integration does not interrupt ongoing synchronization operations, but configuration changes take effect on the next scheduled sync. This ensures that in-progress operations complete successfully before new settings are applied. You can update any combination of configuration parameters in a single request, and unchanged fields will retain their existing values.

Updatable Configuration Fields:

• name: Update the integration's display name for better organization
• description: Modify the description to reflect current usage or purpose
• blueprintId: Reassign the integration to a different blueprint for organizational purposes
• datasetId: Change the target dataset where Notion content is synchronized
• token: Update the Notion API token when credentials are rotated or changed
• syncSchedule: Adjust how frequently content is synchronized (@hourly, @daily, @weekly, or cron expressions)
• expiresIn: Modify record expiration time in milliseconds (max: 3 months / 7,776,000,000 ms)
• meta: Update custom metadata for tracking or organizational purposes

Common Update Scenarios:

Changing Sync Frequency:

Useful when content updates more frequently than initially anticipated.

Rotating API Credentials:

Required when Notion access tokens expire or are regenerated.

Redirecting to New Dataset:

Useful when reorganizing knowledge bases or promoting from staging to production.

Important Considerations:

• Configuration changes take effect on the next scheduled sync, not immediately
• Changing the dataset will cause future syncs to populate the new dataset; existing data in the old dataset is not automatically migrated
• The expiresIn value must be between 0 and three months (7,776,000,000 milliseconds)
• Setting token to null or empty string will remove the authentication token (requires re-authentication)
• Schedule changes do not affect currently running synchronization operations

Token Security: When updating the token, provide the full new token value. The API will securely store it and never expose the actual token value in subsequent fetch or list operations (always masked as ********).

Deleting a Notion Integration

To permanently remove a Notion integration and stop all content synchronization from the associated Notion workspace, use the delete endpoint. This operation irreversibly removes the integration configuration, cancels any scheduled sync operations, and disconnects the integration from its associated dataset. This is typically used when you no longer need to sync content from a particular Notion workspace, when migrating to a different integration approach, or when cleaning up unused integrations from your account.

Deleting a Notion integration does not automatically remove the content that was previously synchronized into the associated dataset. Records that were imported from Notion remain in the dataset unless explicitly deleted. This design ensures that valuable content is preserved even after the integration is removed, giving you the option to manually manage or migrate existing data before deletion.

The response confirms successful deletion:

What Gets Deleted:

• The Notion integration configuration and all associated settings
• The stored Notion API token and authentication credentials
• All scheduled synchronization tasks for this integration
• Metadata and configuration history for the integration

What Is NOT Deleted:

• Records previously synchronized from Notion that now exist in the dataset
• The associated dataset itself (remains intact and operational)
• Any blueprints or other resources that referenced this integration
• Audit logs and event logs documenting past integration operations

Important Considerations:

Before Deleting:

• Verify that you no longer need content updates from this Notion workspace
• Consider whether you want to preserve synchronized records in the dataset
• Check if any bots or applications depend on content from this integration
• Export integration configuration if you might want to recreate it later

After Deletion:

• All scheduled syncs will immediately stop, and no new content will be imported
• The integration cannot be recovered; you must recreate it from scratch if needed
• Existing dataset records remain available but will not receive updates from Notion
• You can safely delete records from the dataset separately if you no longer need them

Alternative to Deletion: If you want to temporarily pause synchronization without losing the integration configuration, consider updating the syncSchedule to a less frequent interval or disabling automatic syncing entirely, rather than deleting the integration. This preserves your configuration for future use.

Syncing Notion Content

Syncing a Notion integration initiates the process of importing content from your Notion workspace into a ChatBotKit dataset, making your Notion pages, databases, and knowledge accessible to your conversational AI bots. This synchronization process extracts text content, maintains document structure, and populates your dataset with searchable, conversable information from Notion.

The sync operation runs asynchronously as a background task, processing your Notion workspace according to configured limits and schedules. It respects rate limiting to ensure system stability and processes content incrementally, allowing you to work with large Notion workspaces without overwhelming system resources.

Sync Process and Behavior

When you trigger a sync operation, the system launches an asynchronous worker that connects to your Notion workspace using the configured authentication token. The worker discovers pages and databases, extracts content, and imports it into the associated dataset as searchable records.

The sync respects plan-based limits for both the number of pages processed and the maximum execution time. These limits ensure fair resource usage across the platform while allowing sufficient processing capacity for typical Notion workspaces. The system automatically applies appropriate limits based on your account plan.

Content extracted from Notion is processed and stored as dataset records with metadata indicating their source. Each record includes the page content, structural information, and references back to the original Notion pages. This metadata enables traceability and helps maintain connections between your dataset and source documents.

Rate Limiting and Scheduling

Manual sync operations are rate-limited to prevent excessive API usage and ensure system stability. You can trigger a manual sync once every 15 minutes per integration. This rate limit prevents accidental duplicate syncs while still allowing reasonable manual control over content updates.

If you've configured automatic sync scheduling on the integration, manual syncs work alongside scheduled syncs. The lastSyncedAt timestamp is updated after each successful sync, whether manual or automatic, helping you track content freshness and sync frequency.

Prerequisites and Requirements

Before syncing a Notion integration, ensure:

Dataset Association: The integration must be connected to a dataset where Notion content will be imported. Attempting to sync without a dataset will result in a conflict error.

Valid Authentication: The Notion token must be valid and have appropriate permissions to access the workspace content you want to sync. Expired or revoked tokens will cause sync failures.

Available Resources: Your account must have sufficient dataset record limits available. The system checks limits before beginning the sync to prevent partial imports that exceed your plan allocation.

Understanding Sync Results

The sync operation returns immediately with the integration ID, but the actual content import happens asynchronously in the background. You can monitor sync progress by checking the lastSyncedAt timestamp on the integration and reviewing dataset record counts.

Successful syncs update the dataset with new and modified content from Notion. The exact behavior depends on your sync configuration, including whether records expire and how frequently content is refreshed.

Note: This operation is rate-limited to once every 15 minutes per integration. Attempting to sync more frequently will result in a rate limit error.