Zum Hauptinhalt springen

So funktionieren Docs

Diese Seite erklärt das Dokumentmodell und die Mechanik hinter jeder Docs-Operation: wie Dokumente in einen Baum nesten, wie Zugriff gescoped ist, wie die Hierarchie lazy gebrowst wird, wie Markdown asynchron gelesen und geschrieben wird und wie Volltextsuche funktioniert. Für eine schnelle Orientierung und Copy-Paste-Beispiele beginnen Sie mit der Docs-Einführung.

Das Dokumentmodell​

Ein Dokument hat:

  • Title — seinen Namen.
  • Body — den Rich-Text-Inhalt, gelesen und geschrieben als Markdown.
  • Parent — optionaler Verweis auf ein anderes Dokument; das baut den Baum.
  • Icon und Cover — optionales Emoji/Icon und Cover-Bild.

Dokumente nesten über ihr parent und bilden eine Hierarchie:

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

Dokumente ohne Parent sitzen an der Wurzel.

Zugriffsmodell​

Zugriff folgt Besitz und Freigabe. Mit einem Personal Access Token liefert die API nur Dokumente, die der authentifizierte Benutzer besitzt oder die mit ihm als Teilnehmer geteilt wurden. Das Löschen eines Dokuments ist auf den Owner beschränkt und ist ein wiederherstellbares Soft-Delete.

Den Baum browsen​

Der Tree-Endpunkt durchläuft die Hierarchie breadth-first:

  • Rufen Sie ihn ohne parentId für Root-Dokumente auf oder übergeben Sie eine Dokument-ID für diesen Teilbaum.
  • Steuern Sie die Tiefe mit depth (1–10, Standard 3).

Jeder Knoten trägt ein Flag hasChildren, was lazy-loading Explorer erleichtert — holen Sie eine tiefere Ebene erst, wenn ein Benutzer einen Knoten aufklappt. Der Baum ist auf 500 Dokumente pro Antwort begrenzt; bei Truncation enthält die Antwort nextParentIds, damit Sie die restlichen Zweige weiter laden können.

Inhalt lesen und schreiben​

Inhalt ist immer Markdown. Lesen Sie ihn über den …/md-Endpunkt des Dokuments, der { "content": "…" } liefert (leerer String, wenn das Dokument keinen Body hat).

Zum Schreiben POST an denselben Pfad mit operation und content:

  • replace — den gesamten Body überschreiben.
  • append — am Ende anhängen.
  • prepend — am Anfang voranstellen.

Inhaltsaktualisierungen sind asynchron: Die API stellt die Änderung in die Queue und liefert HTTP 202 Accepted. Der neue Inhalt erscheint kurz danach. Das Anlegen eines Dokuments mit initialem content folgt demselben async-Pfad — die Seite wird sofort erstellt und der Body kurz danach befüllt.

Dokumente verwalten​

  • Anlegen — POST mit title, optionalem parent (zum Nesten) und optionalem initialem content.
  • Metadaten aktualisieren — PATCH, um title, icon oder cover zu ändern.
  • Löschen — soft-deletet das Dokument (nur Owner; wiederherstellbar).

Suche​

Der Search-Endpunkt führt Volltextsuche über jedes Dokument aus, auf das Sie Zugriff haben. Übergeben Sie q für die Query und steuern Sie optional sortBy (createdAt / updatedAt, Standard updatedAt), sortOrder (asc / desc, Standard desc) und limit (1–50, Standard 20).

Ergebnisse kommen mit hervorgehobenen Treffern in Titel und Body sowie der Ancestor-Kette jedes Hits (parents), damit Sie zeigen können, wo ein Ergebnis im Baum liegt.

tipp

Für Suche, die Dokumente und andere Entitätstypen (Channels, Todos, Drive-Dateien und mehr) in einem Aufruf abdeckt, verwenden Sie stattdessen die globale Search API.

Authentifizierung & Scope​

Docs-Endpunkte erfordern ein Personal Access Token (cp_pat_) mit dem Scope access_docs. Ein Token ohne Scope erhält 403. Siehe Authentifizierung.

Referenz​