notion

O que notion faz?

Prefira a CLI oficial ntn. Use curl apenas quando ntn não estiver disponível ou uma requisição crua for mais clara.

Configuração

npm install -g ntn
ntn --version
ntn login

Autenticação via script/headless:

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

ntn api define Authorization e Notion-Version automaticamente. Por padrão, usa o login da CLI, ou NOTION_API_TOKEN quando definido.

Inspeção

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

Páginas

Ajudantes centrados em Markdown:

ntn pages get <page-id>
ntn pages get <page-id> --json
ntn pages create --parent page:<page-id> --content '# Título\n\nCorpo'
ntn pages create --parent data-source:<data-source-id> < page.md
ntn pages update <page-id> --content '# Atualizado'
ntn pages update <page-id> < page.md
ntn pages trash <page-id> --yes

Notas:

• pages get imprime Markdown com propriedades da página como frontmatter.
• Entrada de conteúdo: --content, stdin ou editor em um TTY.
• Referências de pai: page:<id>, database:<id>, data-source:<id>.
• Para propriedades/templates/API de Páginas completa, use ntn api v1/pages.

Fontes de dados

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 'Data desc'
ntn datasources query <data-source-id> --filter '{"property":"Feito","checkbox":{"equals":true}}'

Use resolve quando você tiver um ID de banco de dados. Para consultar, precisa de um ID de fonte de dados.

API crua

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[Nome][title][0][text][content]=Novo item'
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]=Olá'

Sintaxe de entrada:

• path=value: campo string no corpo.
• path:=json: campo JSON tipado no corpo.
• name==value: parâmetro de consulta.
• Header:Value: cabeçalho da requisição.
• --data '<json>' ou stdin JSON para corpos maiores.
• Apenas uma fonte de corpo por requisição.

Arquivos

ntn files create < image.png
ntn files create --filename photo.png --content-type image/png < /tmp/photo
ntn files create --external-url https://example.com/photo.png
ntn files get <upload-id>
ntn 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 podem exigir plano Business/Enterprise e ativação do workspace.

Fallback com curl

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"

Notas de versão

• Versão atual mais recente da API: 2026-03-11.
• Use in_trash, não archived.
• O posicionamento de blocos anexados usa position, não after de forma plana.
• Bloco transcription renomeado para meeting_notes.
• Bancos de dados podem conter múltiplas fontes de dados; pais de página geralmente usam data_source_id.