Notion

The engine reads the pages and database rows shared with your integration into a knowledge base.

Content is read in place, in your deployment, in your own account. LightHouse receives ids, hashes and counts only. The records are not transmitted, and LightHouse does not open the credential.

The way to connect

Way	What you do
Paste an internal integration’s secret	Make an internal integration in your workspace with Read content only, share the pages and databases it may read with it, and paste its secret (ntn_)

Connect in LightHouse

You need the Client administrator (client_admin) role, signed in as a person, and a deployment whose engine reads this connector (compatibility reference) and keeps credentials in your own store.

1. Go to Setup and admin → Connectors, find Notion (search for it, or filter by its family), and choose Connect.
2. Fill in optionally databases (ids, to read only those databases’ rows).
3. Under What agents may do with it, keep Read only unless your agents are to write through approved cards.
4. Paste the integration’s secret. Your browser seals it to your deployment; LightHouse never sees it.
5. Your deployment keeps it and checks it at the provider. The card shows the result.

Connect in code

- id: notion-knowledge
  purpose: Read Notion into the knowledge base.
  executor: python
  target: aal_engine.ingest.connector:run_card
  overseer: ops-lead@example.com
  budget_usd: 0
  effect: internal
  source:
    kind: notion
    databases: []                     # optional: only these databases' rows
    label: internal
    credential_secret: <connection id>
    requires:
      reads: [notion:the pages and databases shared with the integration]
      reason: the agents answer from the team's own wiki

Capabilities

• Read only: the integration’s Read content capability. Only what someone shares with the integration is read: sharing a page with it is the decision to let the agents read it.
• Read and write: give the integration Update content and Insert content, for agents that write through approved cards.
• The health check: your deployment asks Notion for the integration’s own bot user. Notion does not state an integration’s capabilities, so the card says the sharing decides.
• One host: api.notion.com.

Where the credential is held

LightHouse never opens this credential. It is sealed in your browser, or by lighthouse-ai connect notion --credential-stdin, to your deployment’s own key, and your deployment keeps it in your own secrets store under lighthouse/connectors/notion/<connection id>. A request that sends it to LightHouse unsealed is refused with 422 sealing_required. LightHouse keeps the connection’s fingerprint, the access level, the scopes the provider states and when it was checked: never the credential, and never what it reads.

See Where every credential is held.

What is indexed

• Pages shared with the integration, with their text to three levels of nesting, and database rows with their properties. A child page is a document of its own.
• How often, and what is read each time: on the card’s schedule. Each pull searches for pages newest first, stopping at the first whose last_edited_time is not after the cursor.
• Deletions: every six hours every shared page’s id is listed; a page moved to the trash, archived or no longer shared is removed.
• Rate limits: Notion allows about three requests a second. The source paces itself to that, and a 429 waits as long as Notion asks.
• Never read: pages not shared with the integration, comments and files.

Check it worked

• The source’s run note in your deployment: written N, unchanged N, quarantined N, removed N.
• Agents → Knowledge: documents from notion.
• Content is read in place, in your deployment. LightHouse receives ids, hashes and counts only; the records are not transmitted.

Removing it

On the card, choose Disconnect. Your deployment deletes the credential from your store. Delete the integration in Notion (Settings → Connections → Develop or manage integrations), or stop sharing pages with it. Documents already written stay in the corpus until you delete them.