Skip to main content

​
Introduction

Documents in Copera are rich text pages that can be organized hierarchically. This guide explains the document model, how access control works, and how to manipulate document content through the Public API.

​
Document Structure

Each document contains the following key properties:
  • Title — the name of the document.
  • Body — the rich text content, accessible as Markdown via the API.
  • Parent — an optional reference to a parent document, enabling nested hierarchies.
  • Icon — an optional emoji or icon for the document.
  • Cover — an optional cover image.

​
Hierarchy

Documents can be nested inside other documents using the parent property. This allows you to create structured document trees:
  • Document A
    • Document B (parent = Document A)
      • Document C (parent = Document B)

​
Access Model

Document access is determined by ownership and sharing:
  • Owned documents — documents you created are always accessible to you.
  • Shared documents — documents shared with you via participants are also accessible.
When using a Personal Access Token, the API returns documents based on the authenticated user’s access. You can only interact with documents you own or that have been shared with you.

​
Content Manipulation

The API supports three operations for updating document content:
  • Replace — overwrites the entire document body with new content.
  • Append — adds content to the end of the existing body.
  • Prepend — adds content to the beginning of the existing body.
All content is provided and returned as Markdown.

​
Asynchronous Updates

Content updates are processed asynchronously. When you submit a content update, the API queues the operation and returns an HTTP 202 Accepted response. The content will be updated shortly after.
The API provides full-text search across all documents accessible to the authenticated user. Search is powered by Meilisearch and returns results with highlighted matches, making it easy to display relevant snippets.

​
Example Workflow

A typical workflow for managing documents through the API:
  1. Create a document — POST /public/v1/docs/ with a title.
  2. Set content — POST /public/v1/docs/{docId}/md with Markdown content using the replace operation.
  3. Search documents — GET /public/v1/docs/search?q=keyword to find documents by content.
  4. Update content — POST /public/v1/docs/{docId}/md with the append operation to add new content.
  5. Retrieve content — GET /public/v1/docs/{docId}/md to read the current Markdown body.

​
Summary

  • Documents have a title, body, and optional parent for nesting.
  • Access is based on ownership and sharing via participants.
  • Content can be replaced, appended, or prepended as Markdown.
  • Content updates are asynchronous (HTTP 202).
  • Full-text search with highlighted results is available across your accessible documents.