> ## Documentation Index
> Fetch the complete documentation index at: https://developers.essal.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Document

> Learn how to create a document in Essal Office via the API, set permissions, and upload attachments.

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:

```bash theme={null}
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:

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
# 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" }
```

<Tip>
  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`.
</Tip>

## Publishing a Document

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

```bash theme={null}
POST /v1/office/documents/doc_01HXYZABC/publish
```

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