Vai al contenuto principale

Come funzionano i Docs

Questa pagina spiega il modello documento e le meccaniche dietro ogni operazione Docs: come i documenti si annidano in un albero, come è scopato l'accesso, come sfogliare la gerarchia in modo lazy, come il contenuto markdown viene letto e scritto in modo asincrono e come funziona la full-text search. Per un orientamento rapido ed esempi copy-paste, parti dall'introduzione Docs.

Il modello documento​

Un documento ha:

  • Title — il suo nome.
  • Body — il contenuto rich-text, letto e scritto come markdown.
  • Parent — un riferimento opzionale a un altro documento, che costruisce l'albero.
  • Icon e Cover — emoji/icon e cover image opzionali.

I documenti si annidano tramite il loro parent, formando una gerarchia:

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

I documenti senza parent stanno alla root.

Modello di accesso​

L'accesso segue ownership e sharing. Con un Personal Access Token, l'API restituisce solo i documenti che l'utente autenticato possiede o che gli sono stati condivisi come participant. Eliminare un documento è riservato al suo owner ed è uno soft-delete recuperabile.

Sfogliare l'albero​

L'endpoint tree percorre la gerarchia breadth-first:

  • Chiamalo senza parentId per i documenti a livello root, oppure passa un document id per recuperare quel subtree.
  • Controlla quanto scende in profondità con depth (1–10, default 3).

Ogni nodo porta un flag hasChildren, che rende facili gli explorer lazy-loading — fetcha un livello più profondo solo quando un utente espande un nodo. L'albero è limitato a 500 documenti per response; quando tronca, la response include nextParentIds così puoi continuare a recuperare i branch rimanenti.

Leggere e scrivere contenuto​

Il contenuto è sempre markdown. Leggilo dall'endpoint …/md del documento, che restituisce { "content": "…" } (una stringa vuota quando il documento non ha body).

Per scrivere contenuto, POST sullo stesso path con un operation e content:

  • replace — sovrascrive l'intero body.
  • append — aggiunge in fondo.
  • prepend — aggiunge all'inizio.

Gli aggiornamenti di contenuto sono asincroni: l'API mette in coda la modifica e restituisce HTTP 202 Accepted. Il nuovo contenuto compare un momento dopo. Creare un documento con content iniziale segue lo stesso percorso async — la pagina viene creata immediatamente e il body viene riempito poco dopo.

Gestire i documenti​

  • Create — POST un title, con un parent opzionale (per l'annidamento) e un content iniziale opzionale.
  • Update metadata — PATCH per cambiare title, icon o cover.
  • Delete — soft-delete del documento (solo owner; recuperabile).

Cercare​

L'endpoint search esegue full-text search su ogni documento a cui puoi accedere. Passa q per la query e opzionalmente controlla sortBy (createdAt / updatedAt, default updatedAt), sortOrder (asc / desc, default desc) e limit (1–50, default 20).

I risultati tornano con match evidenziati nel title e nel body, più la catena di antenati di ogni hit (parents), così puoi mostrare dove un risultato vive nell'albero.

suggerimento

Per una search che copre documenti e altri tipi di entità (channels, todos, file del drive e altro) in una sola chiamata, usa invece la Search API globale.

Autenticazione e scope​

Gli endpoint Docs richiedono un Personal Access Token (cp_pat_) con lo scope access_docs. Un token senza lo scope ottiene un 403. Vedi Autenticazione.

Riferimento​