<aside> ❗ Dica do Notion: Use esta página como um exemplo de como você pode estruturar sua referência de API e organizá-la no Notion. A base de dados de pontos finais também inclui um modelo de pontos finais para documentação adicional.

</aside>

Genérico

Introdução

A referência é sua chave para uma compreensão abrangente da API do Notion.

<aside> ❗ Você precisa de um token de integração para interagir com a API do Notion. Você pode encontrar um token depois de criar uma integração na página de configurações. Se esta for sua primeira experiência com a API do Notion, recomendamos começar com o guia de introdução (em inglês) para saber como criar uma integração.

</aside>

Convenções

O URL base para enviar todas as solicitações de API é https://api.notion.com. O HTTPS é necessário para todas as solicitações de API.

A API do Notion segue as convenções RESTful sempre que possível, com a maioria das operações realizadas por meio de solicitações GET, POST, PATCH e DELETE em recursos de página e banco de dados. Os corpos de solicitação e resposta são codificados como JSON.

CONVENÇÕES JSON

• Os recursos de nível superior têm uma propriedade "object". Essa propriedade pode ser usada para determinar o tipo do recurso (por exemplo, "database", "user" etc.).
• Os recursos de nível superior são endereçáveis por uma propriedade "id" UUIDv4 . Você pode omitir os traços do ID ao fazer solicitações à API, por exemplo, ao copiar o ID de um URL do Notion.
• Os nomes das propriedades estão em snake_case (não em camelCase ou kebab-case).
• Os valores temporais (datas e datetimes) são codificados em cadeias de caracteres ISO 8601. Os datetimes incluirão o valor da hora (2020-08-12T02:12:33.231Z), enquanto as datas incluirão somente a data (2020-08-12)
• A API do Notion não oferece suporte a cadeias de caracteres vazias. Para cancelar a definição de um valor de cadeia de caracteres para propriedades como um objeto de valor de propriedade url, por exemplo, use um null explícito em vez de "".

Amostras de código e SDKs

São mostrados exemplos de solicitações e respostas para cada ponto final. As solicitações são mostradas usando o JavaScript SDK e o cURL do Notion. Esses exemplos facilitam a cópia, a colagem e a modificação à medida que você cria sua integração.

Os SDKs do Notion são projetos de código aberto que você pode instalar para começar a criar facilmente. Você também pode escolher qualquer outra linguagem ou biblioteca que lhe permita fazer solicitações HTTP.

Paginação

Os pontos finais que retornam listas de objetos suportam solicitações de paginação baseadas em cursor. Por padrão, o Notion retorna dez itens por chamada de API. Se o número de itens em uma resposta de um ponto de extremidade de suporte exceder o padrão, uma integração poderá usar a paginação para solicitar um conjunto específico de resultados e/ou limitar o número de itens retornados.

PONTOS FINAIS COMPATÍVEIS

RESPOSTAS

Limites de solicitação

Para garantir uma experiência de desenvolvedor consistente para todos os usuários da API, a API do Notion é limitada por taxa e os limites básicos de tamanho se aplicam aos parâmetros de solicitação.

Limites de taxas

As solicitações com taxa limitada retornarão um código de erro "rate_limited" (status de resposta HTTP 429). O limite de taxa para solicitações de entrada por integração é uma média de três solicitações por segundo. São permitidas algumas explosões além da taxa média.

<aside> ❗ Os limites de taxas podem mudar

No futuro, planejamos ajustar os limites de taxa para equilibrar a demanda e a confiabilidade. Também poderemos introduzir limites de taxa distintos para espaços de trabalho em diferentes planos de preços.

</aside>

Limites de tamanho

O Notion limita o tamanho de determinados parâmetros e a profundidade dos itens nas solicitações. As solicitações que excederem qualquer um desses limites retornarão o código de erro "validation_error" (status de resposta HTTP 400) e conterão detalhes mais específicos na propriedade "message".

Códigos de status

Os códigos de resposta HTTP são usados para indicar classes gerais de sucesso e erro.

Código de sucesso

Códigos de erro

As respostas de erro contêm mais detalhes sobre o erro no corpo da resposta, nas propriedades "code" e "message".

Controle de versão

Nossas versões de API são nomeadas de acordo com a data de lançamento da versão. Por exemplo, nossa versão mais recente é 2022-06-28.

Você define a versão ao incluir um cabeçalho Notion-Version. É necessário definir o cabeçalho Notion-Version.

curl <https://api.notion.com/v1/users/01da9b00-e400-4959-91ce-af55307647e5> \\
  -H "Authorization: Bearer secret_t1CdN9S8yicG5eWLUOfhcWaOscVnFXns"
  -H "Notion-Version: 2022-06-28"

Objetos

Usuários

Onde os objetos do usuário aparecem na API

Os objetos do usuário aparecem na API em quase todos os objetos retornados pela API, inclusive:

• Objeto de bloco em created_by e last_edited_by.
• Objeto de página em created_by e last_edited_by e em itens de propriedade de people.
• Objeto de banco de dados em created_by e last_edited_by.
• Objeto de texto rico, como menções de usuário.
• Objeto de propriedade quando a propriedade é uma propriedade de people.

Os objetos de usuário sempre conterão chaves de object e id, conforme descrito abaixo. As propriedades restantes podem aparecer se o usuário estiver sendo renderizado em um texto rico ou em um contexto de propriedade de página, e se o bot tiver os recursos corretos para acessar essas propriedades. Para saber mais sobre recursos, consulte o guia Recursos e o guia Autorização.

Todos os usuários

Esses campos são compartilhados por todos os usuários, incluindo pessoas e bots. Os campos marcados com * estão sempre presentes.

Arquivo

Os objetos de arquivo contêm dados sobre um arquivo carregado no Notion ou dados sobre um arquivo externo vinculado ao Notion.

{
  "type": "file",
  "file": {
    "url": "<https://s3.us-west-2.amazonaws.com/secure.notion-static.com/7b8b0713-dbd4-4962-b38b-955b6c49a573/My_test_image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAT73L2G45EIPT3X45%2F20221024%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20221024T205211Z&X-Amz-Expires=3600&X-Amz-Signature=208aa971577ff05e75e68354e8a9488697288ff3fb3879c2d599433a7625bf90&X-Amz-SignedHeaders=host&x-id=GetObject>",
    "expiry_time": "2022-10-24T22:49:22.765Z"
  }
}

Os tipos de bloco de página, integrações, imagem, vídeo, arquivo, pdf e marcadores contêm objetos de arquivo. Os valores dos objetos ícone e capa também contêm objetos de arquivo.

Cada objeto de arquivo inclui os seguintes campos:

Pontos finais

Pontos finais