Notion

Was macht Notion?

Die offizielle ntn CLI bevorzugen. curl nur verwenden, wenn ntn nicht verfügbar ist oder ein roher Request klarer ist.

Einrichtung

npm install -g ntn
ntn --version
ntn login

Skript-/Headless-Authentifizierung:

export NOTION_API_TOKEN=secret_oder_ntn_token
export NOTION_API_VERSION=2026-03-11

ntn api setzt Authorization und Notion-Version automatisch. Standardmäßig wird die CLI-Anmeldung verwendet, oder NOTION_API_TOKEN, wenn gesetzt.

Inspizieren

ntn doctor
ntn api ls
ntn api ls --json
ntn api v1/comments --help
ntn api v1/comments --spec -X POST
ntn api v1/comments --docs -X POST

Seiten

Markdown-zentrierte Helfer:

ntn pages get <page-id>
ntn pages get <page-id> --json
ntn pages create --parent page:<page-id> --content '# Titel\n\nTextkörper'
ntn pages create --parent data-source:<data-source-id> < seite.md
ntn pages update <page-id> --content '# Aktualisiert'
ntn pages update <page-id> < seite.md
ntn pages trash <page-id> --yes

Hinweise:

• pages get gibt Markdown mit Seiten-Eigenschaften als Frontmatter aus.
• Inhaltseingabe: --content, stdin oder Editor in einem TTY.
• Elternreferenzen: page:<id>, database:<id>, data-source:<id>.
• Für Eigenschaften/Vorlagen/die vollständige Seiten-API ntn api v1/pages verwenden.

Datenquellen

ntn datasources resolve <database-id>
ntn datasources resolve <database-id> --json
ntn datasources query <data-source-id>
ntn datasources query <data-source-id> --limit 50 --json
ntn datasources query <data-source-id> --sort 'Datum absteigend'
ntn datasources query <data-source-id> --filter '{"property":"Erledigt","checkbox":{"equals":true}}'

resolve bei einer Datenbank-ID verwenden. query benötigt eine Datenquellen-ID.

Rohe API

ntn api v1/users/me
ntn api v1/search query=roadmap page_size:=10
ntn api v1/pages 'parent[data_source_id]='"$DS_ID" 'properties[Name][title][0][text][content]=Neues Element'
ntn api "v1/pages/$PAGE_ID" -X PATCH in_trash:=true
ntn api "v1/blocks/$PAGE_ID/children" -X PATCH \
  'children[0][type]=paragraph' \
  'children[0][paragraph][rich_text][0][text][content]=Hallo'

Eingabesyntax:

• path=value: String-Body-Feld.
• path:=json: Typisiertes JSON-Body-Feld.
• name==value: Query-Parameter.
• Header:Value: Request-Header.
• --data '<json>' oder stdin JSON für größere Bodies.
• Nur eine Body-Quelle pro Request.

Dateien

ntn files create < bild.png
ntn files create --filename foto.png --content-type image/png < /tmp/foto
ntn files create --external-url https://example.com/foto.png
ntn files get <upload-id>
tn files list

Workers

ntn workers new
ntn workers deploy
ntn workers list --json
ntn workers runs list --json
ntn workers runs logs <run-id>

Workers erfordern möglicherweise einen Business/Enterprise-Plan und die Aktivierung im Workspace.

Curl-Fallback

curl -sS "https://api.notion.com/v1/users/me" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2026-03-11" \
  -H "Content-Type: application/json"

Versionshinweise

• Aktuelle API-Version: 2026-03-11.
• in_trash verwenden, nicht archived.
• Block-Positionierung beim Anhängen verwendet position, nicht das flache after.
• Block transcription in meeting_notes umbenannt.
• Datenbanken können mehrere Datenquellen enthalten; Seiten-Eltern verwenden im Allgemeinen data_source_id.