Create a Document

Essal Office allows you to create and manage documents programmatically. This guide walks through creating a new document, setting its initial permissions, and attaching a file.

Creating a Document

Send a POST request to the documents endpoint with a title and optional initial content:

curl -X POST https://api.essal.cloud/v1/office/documents \
  -H "X-API-Key: esk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Q4 Planning Notes",
    "content": "<h1>Q4 Planning</h1><p>Initial draft.</p>",
    "content_type": "html"
  }'

A successful response returns the full document object:

{
  "id": "doc_01HXYZABC",
  "title": "Q4 Planning Notes",
  "status": "draft",
  "owner_id": "usr_01HXYZ1234",
  "created_at": "2026-07-10T09:00:00Z",
  "updated_at": "2026-07-10T09:00:00Z",
  "permissions": {
    "visibility": "private",
    "editors": [],
    "viewers": []
  }
}

Setting Permissions

By default, a new document is private to the creator. Grant access to other users or groups:

PATCH https://api.essal.cloud/v1/office/documents/doc_01HXYZABC/permissions
{
  "visibility": "workspace",
  "editors": ["usr_01HXYZ5678"],
  "viewers": ["grp_01HXYZGRP1"]
}

Permission Level	Description
`private`	Only the owner can view and edit
`workspace`	All workspace members can view
`shared`	Specific users and groups listed in `editors`/`viewers`
`public`	Anyone with the link can view

Uploading Attachments

Attach files to a document by first uploading to the Office file store, then linking:

# Step 1: Upload the file
POST /v1/office/files
Content-Type: multipart/form-data
file=@/path/to/report.pdf

# Response
{ "id": "fil_01HXYZFIL1", "name": "report.pdf", "size_bytes": 204800 }

# Step 2: Attach to document
POST /v1/office/documents/doc_01HXYZABC/attachments
{ "file_id": "fil_01HXYZFIL1" }

Documents support up to 50 attachments and a maximum single file size of 100 MB. For larger files, use the chunked upload endpoint at /v1/office/files/upload/chunked.

Publishing a Document

Move a document from draft to published status to make it available to permitted viewers:

POST /v1/office/documents/doc_01HXYZABC/publish

The document status transitions to published and a office.document.published event fires on the event bus.

Getting Started

Platform Concepts

App Guides — Office

App Guides — Access

App Guides — Sales

App Guides — Careers

App Guides — Project

App Guides — Guard

Integrations

Security & Compliance

Creating a Document

Setting Permissions

Uploading Attachments

Publishing a Document

​Creating a Document

​Setting Permissions

​Uploading Attachments

​Publishing a Document

Creating a Document

Setting Permissions

Uploading Attachments

Publishing a Document