Saltar al contenido principal

Cómo funcionan los Docs

Esta página explica el modelo de documentos y la mecánica detrás de cada operación de Docs: cómo se anidan los documentos en un árbol, cómo se delimita el acceso, cómo explorar la jerarquía de forma diferida, cómo se lee y escribe el contenido markdown de forma asíncrona, y cómo funciona la búsqueda de texto completo. Para una orientación rápida y ejemplos listos para copiar y pegar, comienza con la introducción a Docs.

El modelo de documento​

Un documento tiene:

  • Título: su nombre.
  • Cuerpo: el contenido de texto enriquecido, que se lee y escribe como markdown.
  • Padre: una referencia opcional a otro documento, que es lo que construye el árbol.
  • Icono y Portada: emoji/icono y imagen de portada opcionales.

Los documentos se anidan a través de su parent, formando una jerarquía:

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

Los documentos sin un padre quedan en la raíz.

Modelo de acceso​

El acceso sigue la propiedad y el uso compartido. Con un Personal Access Token, la API solo devuelve los documentos que el usuario autenticado posee o que han sido compartidos con él como participante. Eliminar un documento está restringido a su propietario y es un borrado lógico recuperable.

Explorar el árbol​

El endpoint tree recorre la jerarquía en anchura:

  • Llámalo sin un parentId para los documentos de nivel raíz, o pasa un id de documento para obtener ese subárbol.
  • Controla qué tan profundo desciende con depth (1–10, predeterminado 3).

Cada nodo lleva una bandera hasChildren, lo que facilita los exploradores de carga diferida: solo obtienes un nivel más profundo cuando un usuario expande un nodo. El árbol está limitado a 500 documentos por respuesta; cuando se trunca, la respuesta incluye nextParentIds para que puedas continuar obteniendo las ramas restantes.

Lectura y escritura de contenido​

El contenido siempre es markdown. Léelo desde el endpoint …/md del documento, que devuelve { "content": "…" } (una cadena vacía cuando el documento no tiene cuerpo).

Para escribir contenido, haz POST a la misma ruta con una operation y content:

  • replace: sobrescribe todo el cuerpo.
  • append: agrega al final.
  • prepend: agrega al principio.

Las actualizaciones de contenido son asíncronas: la API encola el cambio y devuelve HTTP 202 Accepted. El nuevo contenido aparece un instante después. Crear un documento con content inicial sigue la misma ruta asíncrona: la página se crea de inmediato y su cuerpo se completa poco después.

Gestión de documentos​

  • Create: POST de un title, con un parent opcional (para anidar) y content inicial opcional.
  • Update metadata: PATCH para cambiar el title, el icon o el cover.
  • Delete: borra lógicamente el documento (solo el propietario; recuperable).

Búsqueda​

El endpoint search ejecuta una búsqueda de texto completo en cada documento al que puedes acceder. Pasa q para la consulta y, opcionalmente, controla sortBy (createdAt / updatedAt, predeterminado updatedAt), sortOrder (asc / desc, predeterminado desc) y limit (1–50, predeterminado 20).

Los resultados regresan con coincidencias resaltadas en el título y el cuerpo, además de la cadena de ancestros de cada coincidencia (parents), para que puedas mostrar dónde vive un resultado en el árbol.

consejo

Para una búsqueda que abarque documentos y otros tipos de entidad (channels, todos, archivos de drive y más) en una sola llamada, usa la API de Search global en su lugar.

Autenticación y alcance​

Los endpoints de Docs requieren un Personal Access Token (cp_pat_) con el alcance access_docs. Un token sin el alcance recibe un 403. Consulta Autenticación.

Referencia​