# Notion

> Connect Notion to LightHouse: an internal integration's secret, the pages shared with it, where the credential is held, and what is indexed.

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](/concepts/telemetry-contract/#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

```yaml
- 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](/connect/#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.

Source: https://docs.atlanticagenticlabs.com/connect/notion/