O Toolkit Notion permite que agentes e fluxos de trabalho interajam com páginas e bancos de dados do Notion. Ele suporta pesquisa de conteúdo, consulta e atualização de registros de banco de dados, leitura e adição de conteúdo de páginas, e criação de novas páginas.
Pré-requisitos
- Uma conta do Notion (o plano gratuito é suficiente)
- Um workspace do Notion (toda conta tem um por padrão)
Criando uma Conexão
Workflow Builder
Agent Builder
- No fluxo de trabalho, adicione um passo do toolkit Notion.
- Clique em Connect with Notion.
- Autorize a conexão na tela de consentimento do Notion e selecione quais páginas e bancos de dados conceder acesso.
No chat, você será solicitado a conectar sua conta do Notion via OAuth quando o toolkit for invocado pela primeira vez.
O toolkit só pode acessar páginas e bancos de dados que foram compartilhados explicitamente com a conexão. Para compartilhar conteúdo, abra a página ou banco de dados no Notion, clique em ··· → Connections e adicione sua integração. Conteúdo no mesmo workspace que não foi compartilhado não é visível.
Ferramentas Disponíveis
| Ferramenta | Descrição |
|---|
| Search | Pesquise em todas as páginas e bancos de dados compartilhados por título |
| List Databases | Retorne todos os bancos de dados que a conexão pode acessar |
| Get Database | Retorne o esquema (nomes e tipos de colunas) de um banco de dados específico |
| Query Database | Recupere registros de um banco de dados com filtros e ordenação opcionais |
| Get Page | Recupere os valores das propriedades e metadados de uma página ou registro de banco de dados |
| Create Page | Crie um novo registro de banco de dados ou sub-página |
| Update Page | Atualize propriedades de uma página existente ou a arquive |
| Get Page Content | Leia o texto do corpo (blocos de conteúdo) de uma página |
| Append Content | Adicione novos blocos de conteúdo ao final de uma página |
Search
Pesquisa em todas as páginas e bancos de dados compartilhados, retornando correspondências por título.
Entradas principais:
| Entrada | Descrição |
|---|
| Query | O texto a ser pesquisado |
| Filter Type | Opcionalmente restrinja a page ou database. Deixe em branco para pesquisar ambos. |
| Page Size | Número de resultados a retornar (padrão: 10, máximo: 100) |
Referenciando resultados em passos posteriores:
- ID do primeiro resultado:
{{ step.output.results[0].id }}
Exemplo de caso de uso: Antes de criar um novo registro de cliente, pesquise pelo nome do cliente. Se count for maior que 0, o cliente já existe — use o id do registro existente em vez de criar um duplicado.
Ações de Banco de Dados
List Databases
Retorna todos os bancos de dados que a conexão pode acessar, com seus nomes e IDs.
Entradas principais:
| Entrada | Descrição |
|---|
| Page Size | Número de bancos de dados a retornar (padrão: 20, máximo: 100) |
Quando usar: Execute isso uma vez em um fluxo de trabalho de teste para descobrir seus IDs de banco de dados. Copie o id do banco de dados desejado e codifique-o diretamente nos passos seguintes.
Get Database
Retorna o esquema de um banco de dados específico — seus nomes de colunas e tipos de propriedades.
Entradas principais:
| Entrada | Descrição |
|---|
| Database ID | O ID do banco de dados — do List Databases ou da URL do Notion: o segmento antes do ?v= |
Quando usar: Execute isso antes de escrever os passos Create Page ou Update Page. Ele informa os nomes exatos das propriedades (diferenciais entre maiúsculas e minúsculas) e seus tipos, o que determina o formato JSON a ser usado no campo Properties.
O Get Database mostra tipos e nomes de propriedades, mas não os valores de opções disponíveis para campos Select. Para ver as opções de select válidas, abra o banco de dados diretamente no Notion.
Query Database
Recupera registros de um banco de dados com filtragem e ordenação opcionais.
Entradas principais:
| Entrada | Descrição |
|---|
| Database ID | Qual banco de dados consultar |
| Filter | Um objeto JSON de filtro (veja exemplos abaixo). Deixe em branco para retornar todos os registros. |
| Sorts | Um array JSON de regras de ordenação (veja exemplos abaixo) |
| Page Size | Número de registros a retornar (padrão: 20, máximo: 100) |
Exemplos de filtro:
Filtro único — registros onde Status é igual a “In Progress”:
{
"property": "Status",
"select": { "equals": "In Progress" }
}
Filtro por checkbox:
{
"property": "Done",
"checkbox": { "equals": false }
}
Filtro por data — registros com Data de Entrega antes de uma data específica:
{
"property": "Due Date",
"date": { "before": "2026-05-26" }
}
Filtro combinado com lógica AND:
{
"and": [
{ "property": "Status", "select": { "equals": "In Progress" } },
{ "property": "Done", "checkbox": { "equals": false } }
]
}
Ordenação — mais recente primeiro:
[
{ "property": "Created time", "direction": "descending" }
]
Referenciando resultados em passos posteriores:
- ID do primeiro resultado:
{{ step.output.results[0].id }}
- Status do primeiro resultado:
{{ step.output.results[0].properties.Status }}
- Título do primeiro resultado:
{{ step.output.results[0].title }}
Ações de Página
Get Page
Recupera os valores das propriedades e metadados de uma página ou registro de banco de dados específico.
Entradas principais:
| Entrada | Descrição |
|---|
| Page ID | O ID da página — da URL do Notion ou dos resultados do Query Database ou Search |
Referenciando valores em passos posteriores:
- Status:
{{ step.output.page.properties.Status }}
- Título:
{{ step.output.page.title }}
- Page ID:
{{ step.output.page.id }}
Exemplo de caso de uso: Um trigger é acionado com um ID de página. Use Get Page para ler o Status atual do registro. Se Status for “Pending”, continue o fluxo de trabalho — caso contrário, pare.
Create Page
Cria uma nova página — seja como um registro dentro de um banco de dados (nova linha) ou como uma sub-página sob outra página.
Entradas principais:
| Entrada | Descrição |
|---|
| Parent ID | O ID do banco de dados (para uma nova linha) ou o ID da página (para uma sub-página) |
| Parent Type | database_id para adicionar uma linha de banco de dados, page_id para adicionar uma sub-página. Padrão: database_id |
| Title | O título da página ou registro em texto simples |
| Properties | Objeto JSON opcional para valores de campos adicionais. As chaves devem corresponder exatamente aos nomes das propriedades do seu banco de dados — use Get Database para confirmá-las. |
Formato de propriedades por tipo de campo:
// Campo Select
{ "Status": { "select": { "name": "To Do" } } }
// Campo Status (tipo Status integrado do Notion)
{ "Status": { "status": { "name": "In Progress" } } }
// Campo Date
{ "Due Date": { "date": { "start": "2026-06-01" } } }
// Campo Checkbox
{ "Done": { "checkbox": false } }
// Campo Number
{ "Priority Score": { "number": 8 } }
// Campo Rich Text
{ "Notes": { "rich_text": [{ "text": { "content": "Needs review before sending." } }] } }
Exemplo completo — criando uma linha de tarefa:
Título: Follow up with client
Propriedades:
{
"Status": { "select": { "name": "To Do" } },
"Due Date": { "date": { "start": "2026-06-01" } },
"Done": { "checkbox": false }
}
O id retornado pode ser passado para passos posteriores para atualizar ou vincular à nova página.
Update Page
Atualiza as propriedades de uma página existente ou a arquiva.
Entradas principais:
| Entrada | Descrição |
|---|
| Page ID | A página a ser atualizada — do Query Database, Get Page ou Search |
| Properties | Objeto JSON contendo apenas os campos que você deseja alterar (mesmo formato do Create Page). Campos não incluídos permanecem inalterados. |
| Archived | Defina como true para arquivar (exclusão suave) a página |
Exemplo — marcando uma tarefa como concluída:
{
"Status": { "select": { "name": "Done" } },
"Done": { "checkbox": true },
"Completed On": { "date": { "start": "2026-05-26" } }
}
Exemplo — arquivando um registro: Deixe Properties vazio e defina Archived como true. O registro desaparece da visualização do banco de dados, mas pode ser restaurado da lixeira do Notion.
Padrão típico:
- Use Query Database para encontrar o registro e obter seu
id
- Passe esse
id para Update Page para alterar seus campos
Ações de Conteúdo
Get Page Content
Recupera os blocos de conteúdo dentro de uma página do Notion — parágrafos, cabeçalhos, listas com marcadores, etc. Isso é separado das propriedades da página (campos de banco de dados). Use isso para ler o texto do corpo de um documento.
Entradas principais:
| Entrada | Descrição |
|---|
| Page ID | A página da qual ler o conteúdo |
| Page Size | Número de blocos a retornar (padrão: 50, máximo: 100) |
Referenciando valores em passos posteriores:
- Texto do primeiro bloco:
{{ step.output.blocks[0].text }}
- Todos os blocos:
{{ step.output.blocks }}
Exemplo de caso de uso: Obtenha o conteúdo da página, passe todos os blocos de texto para um passo de IA para gerar um resumo e, em seguida, envie esse resumo por email ou Telegram.
Append Content
Adiciona novos blocos de conteúdo ao final de uma página existente do Notion.
Entradas principais:
| Entrada | Descrição |
|---|
| Page ID | A página à qual adicionar conteúdo |
| Children | Um array JSON de objetos de bloco do Notion a serem adicionados |
Exemplo — adicionando um cabeçalho e um parágrafo:
[
{
"object": "block",
"type": "heading_2",
"heading_2": {
"rich_text": [{ "type": "text", "text": { "content": "Execução do Fluxo de Trabalho — 26 de Maio" } }]
}
},
{
"object": "block",
"type": "paragraph",
"paragraph": {
"rich_text": [{ "type": "text", "text": { "content": "3 registros processados. 1 erro encontrado." } }]
}
}
]
Exemplo — adicionando um item de lista com marcadores:
[
{
"object": "block",
"type": "bulleted_list_item",
"bulleted_list_item": {
"rich_text": [{ "type": "text", "text": { "content": "Novo lead: Jane Doe — jane@example.com" } }]
}
}
]
Exemplo de caso de uso: Um fluxo de trabalho roda todas as manhãs, processa dados e adiciona uma entrada de log de uma linha a uma página “Diário” — construindo uma trilha de auditoria contínua sem criar uma nova página a cada vez.
Solução de Problemas
| Sintoma | Causa Provável | Correção |
|---|
401 Unauthorized | Token revogado ou ausente | Reautorize via o fluxo OAuth |
404 Not Found em página ou banco de dados | Conteúdo não compartilhado com a conexão | Compartilhe a página via ··· → Connections |
| Resultados de pesquisa ou consulta vazios | Nada compartilhado com a conexão | Compartilhe pelo menos uma página ou banco de dados |
| Atualização de propriedade ignorada silenciosamente | Incompatibilidade de maiúsculas/minúsculas no nome da propriedade | Use Get Database para confirmar os nomes exatos das propriedades — eles diferenciais entre maiúsculas e minúsculas |
Erro oauth_not_configured | Client ID/secret não salvos no Super Admin | Veja Configuração OAuth do Notion |