Aller au contenu principal

Comment fonctionnent les Docs

Cette page explique le modèle de documents et les mécaniques derrière chaque opération Docs : comment les documents s'imbriquent en arbre, comment l'accès est scopé, comment parcourir la hiérarchie de façon paresseuse, comment le contenu markdown est lu et écrit de façon asynchrone, et comment fonctionne la recherche full-text. Pour une orientation rapide et des exemples à copier-coller, commencez par l'introduction Docs.

Le modèle de document​

Un document a :

  • Title — son nom.
  • Body — le contenu rich-text, lu et écrit en markdown.
  • Parent — une référence optionnelle vers un autre document, ce qui construit l'arbre.
  • Icon et Cover — emoji/icône et image de couverture optionnels.

Les documents s'imbriquent via leur parent, formant une hiérarchie :

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

Les documents sans parent se trouvent à la racine.

Modèle d'accès​

L'accès suit la propriété et le partage. Avec un Personal Access Token, l'API ne renvoie que les documents que l'utilisateur authentifié possède ou qui lui ont été partagés en tant que participant. La suppression d'un document est réservée à son propriétaire et est une soft-delete récupérable.

Parcourir l'arbre​

L'endpoint tree parcourt la hiérarchie en largeur d'abord :

  • Appelez-le sans parentId pour les documents de niveau racine, ou passez un id de document pour récupérer ce sous-arbre.
  • Contrôlez la profondeur de descente avec depth (1–10, défaut 3).

Chaque nœud porte un flag hasChildren, ce qui facilite les explorateurs en chargement paresseux — ne récupérez un niveau plus profond que lorsqu'un utilisateur développe un nœud. L'arbre est plafonné à 500 documents par réponse ; lorsqu'il est tronqué, la réponse inclut nextParentIds pour que vous puissiez continuer à récupérer les branches restantes.

Lire et écrire le contenu​

Le contenu est toujours du markdown. Lisez-le depuis l'endpoint …/md du document, qui renvoie { "content": "…" } (une chaîne vide lorsque le document n'a pas de corps).

Pour écrire du contenu, POST sur le même chemin avec une operation et un content :

  • replace — écraser tout le corps.
  • append — ajouter à la fin.
  • prepend — ajouter au début.

Les mises à jour de contenu sont asynchrones : l'API met le changement en file et renvoie HTTP 202 Accepted. Le nouveau contenu apparaît un instant plus tard. Créer un document avec un content initial suit le même chemin async — la page est créée immédiatement et son corps est rempli peu après.

Gérer les documents​

  • Créer — POST un title, avec un parent optionnel (pour l'imbrication) et un content initial optionnel.
  • Mettre à jour les métadonnées — PATCH pour changer le title, l'icon ou le cover.
  • Supprimer — soft-delete du document (propriétaire uniquement ; récupérable).

Rechercher​

L'endpoint search exécute une recherche full-text sur chaque document auquel vous avez accès. Passez q pour la requête et contrôlez optionnellement sortBy (createdAt / updatedAt, défaut updatedAt), sortOrder (asc / desc, défaut desc), et limit (1–50, défaut 20).

Les résultats reviennent avec des correspondances surlignées dans le titre et le corps, plus la chaîne d'ancêtres de chaque hit (parents), pour que vous puissiez montrer où un résultat se trouve dans l'arbre.

astuce

Pour une recherche qui couvre les documents et d'autres types d'entités (channels, todos, fichiers du drive, et plus) en un seul appel, utilisez plutôt l'API Search globale.

Authentification et scope​

Les endpoints docs exigent un Personal Access Token (cp_pat_) avec le scope access_docs. Un token sans ce scope obtient un 403. Voir Authentification.

Référence​