API Reference
Notion Configuration
Connect Notion through OAuth and synchronize the pages and databases explicitly shared with the integration. The source sharing model is the content selector, so no separate page-selection endpoint is required.
Operations on this page
| Operation | Method and path | Python | Node.js |
|---|---|---|---|
| Read Notion capabilities | GET /api/v2/integrations/providers/notion | providers.get | providers.get |
| Start Notion OAuth | POST /api/v2/integrations/oauth/initiate | connections.oauth.initiate | connections.oauth.initiate |
| Confirm the connection | GET /api/v2/integrations/connections/{connection_id} | connections.get | connections.get |
| Start synchronization | POST /api/v2/integrations/connections/{connection_id}/sync | connections.trigger_sync | connections.triggerSync |
Authentication and scope
| Requirement | Contract |
|---|---|
| Credential | An API key sent as X-API-Key. Connector operations are not end-user scoped. |
| Read scope | integrations:read for every GET. |
| Write scope | integrations:write for every POST, PUT, PATCH and DELETE. |
| Tenant | Derived from the authenticated key. There is no tenant parameter to pass or to get wrong. |
X-End-User-ID | Not used. A connection belongs to the organization, not to one end user. |
1. Check Notion availability
Read the provider record before offering setup so your UI follows the deployed catalog instead of a hard-coded provider list.
import osfrom memorysync import MemorySyncClientclient = MemorySyncClient(api_key=os.environ["MEMORYSYNC_API_KEY"],base_url="https://api.memorysync.io",)provider = client.providers.get("notion")print(provider["is_available"], provider["capabilities"])
GET/api/v2/integrations/providers/{provider_id}
200 OK
2. Authorize Notion
Start OAuth and send the browser to the returned URL. During consent, choose the workspace content that the integration may access.
import osfrom memorysync import MemorySyncClientclient = MemorySyncClient(api_key=os.environ["MEMORYSYNC_API_KEY"],base_url="https://api.memorysync.io",)result = client.connections.oauth.initiate("notion",redirect_url="https://app.example.com/connections/callback",)print(result["authorization_url"], result["connection_id"])
POST/api/v2/integrations/oauth/initiate
200 OK
3. Confirm and sync
Wait for a connected status before starting an incremental sync. Sharing another Notion page later makes it available to a later sync.
import osfrom memorysync import MemorySyncClientclient = MemorySyncClient(api_key=os.environ["MEMORYSYNC_API_KEY"],base_url="https://api.memorysync.io",)connection = client.connections.get("conn_8f21a4")if connection["status"] == "connected":job = client.connections.trigger_sync("conn_8f21a4", job_type="incremental")print(job["id"], job["status"])
GET/api/v2/integrations/connections/{connection_id}
200 OK
POST/api/v2/integrations/connections/{connection_id}/sync
202 Accepted
Errors and next action
| Status | Meaning | Next action |
|---|---|---|
401 | Missing, malformed or inactive API key. | Check server configuration without printing the key. |
403 | The key lacks integrations:read or integrations:write. | Grant the scope on the key, or use a key that has it. |
404 | The connection, object or job is not visible to this tenant. | Confirm the identifier belongs to this organization. |
409 | The connection is in a state that forbids the operation. | Read the connection status first and act on it. |
429 | Rate limited, either by MemorySync or by the upstream provider. | Back off; do not tighten a polling loop in response. |
5xx | Service failure. | Treat a write outcome as uncertain and reconcile by reading the connection back. |