Pular para o conteúdo principal

Como os Docs Funcionam

Esta página explica o modelo de documento e a mecânica por trás de cada operação de Docs: como documentos se aninham em uma árvore, como o acesso é delimitado, como navegar pela hierarquia de forma preguiçosa, como o conteúdo markdown é lido e escrito de forma assíncrona, e como a busca full-text funciona. Para uma orientação rápida e exemplos prontos para copiar e colar, comece pela introdução de Docs.

O modelo de documento​

Um documento tem:

  • Title — seu nome.
  • Body — o conteúdo de rich-text, lido e escrito como markdown.
  • Parent — uma referência opcional a outro documento, que é o que constrói a árvore.
  • Icon e Cover — emoji/ícone e imagem de capa opcionais.

Documentos se aninham pelo seu parent, formando uma hierarquia:

Project Notes
├── Kickoff
│   └── Action Items   (parent = Kickoff)
└── Retrospective      (parent = Project Notes)

Documentos sem um parent ficam na raiz.

Modelo de acesso​

O acesso segue a propriedade e o compartilhamento. Com um Personal Access Token, a API só retorna documentos que o usuário autenticado possui ou que foram compartilhados com ele como participante. Excluir um documento é restrito ao seu dono e é um soft-delete recuperável.

O endpoint tree percorre a hierarquia em largura (breadth-first):

  • Chame-o sem um parentId para documentos de nível raiz, ou passe um id de documento para buscar aquela subárvore.
  • Controle a profundidade da descida com depth (1–10, padrão 3).

Cada nó carrega uma flag hasChildren, o que facilita exploradores com lazy-loading — busque um nível mais profundo apenas quando um usuário expandir um nó. A árvore é limitada a 500 documentos por response; quando ela é truncada, a response inclui nextParentIds para que você possa continuar buscando os ramos restantes.

Lendo e escrevendo conteúdo​

O conteúdo é sempre markdown. Leia-o no endpoint …/md do documento, que retorna { "content": "…" } (uma string vazia quando o documento não tem body).

Para escrever conteúdo, faça POST no mesmo path com uma operation e content:

  • replace — sobrescreve todo o body.
  • append — adiciona ao final.
  • prepend — adiciona ao início.

Atualizações de conteúdo são assíncronas: a API enfileira a mudança e retorna HTTP 202 Accepted. O novo conteúdo aparece um instante depois. Criar um documento com content inicial segue o mesmo caminho assíncrono — a página é criada imediatamente e seu body é preenchido logo em seguida.

Gerenciando documentos​

  • Create — POST de um title, com um parent opcional (para aninhar) e content inicial opcional.
  • Update metadata — PATCH para alterar o title, icon ou cover.
  • Delete — soft-delete do documento (apenas o dono; recuperável).

Buscando​

O endpoint search roda busca full-text em todos os documentos que você pode acessar. Passe q para a query e, opcionalmente, controle sortBy (createdAt / updatedAt, padrão updatedAt), sortOrder (asc / desc, padrão desc) e limit (1–50, padrão 20).

Os resultados voltam com correspondências destacadas no title e no body, além da cadeia de ancestrais de cada hit (parents), para que você possa mostrar onde um resultado vive na árvore.

dica

Para uma busca que abrange documentos e outros tipos de entidade (channels, todos, arquivos do drive e mais) em uma única chamada, use a API de Search global.

Autenticação e escopo​

Endpoints de Docs exigem um Personal Access Token (cp_pat_) com o escopo access_docs. Um token sem o escopo recebe um 403. Veja Autenticação.

Referência​