Request and response objects

Every message is a plain JSON object. You choose the id field, and the core returns it unchanged. That lets you match responses to requests even when working in parallel.

Minimal sequence

{"id":"ping-1","cmd":"ping"}
{"id":"open-1","cmd":"open","path":"/absolute/input.docx","document_id":"my-document"}
{"id":"model-1","cmd":"model"}
{"id":"insert-1","cmd":"mutate","operation_kind":"insert-text","paragraph_index":0,"offset":0,"text":"Hello from the API. ","document_id":"my-document","transaction_order":1,"transition_kind":"api-insert"}
{"id":"save-1","cmd":"save","path":"/absolute/output.docx"}
{"id":"shutdown-1","cmd":"shutdown"}

Required and recommended fields

Field	Purpose	Rule
id	Request/response correlation	Optional. Any JSON value — a string, a number. Returned unchanged, so it should be unique among requests whose response hasn’t arrived yet
cmd	Session command name	One of the names listed in the supported_commands field of the greeting message
path	Input or output file	Absolute path only
document_id	Stable document identity	Pass it in open and in edits. It determines how strictly the order is checked — see the box below
transaction_order	Order of changes	Increases monotonically: 1, 2, 3…
transition_kind	Reason or transition type	A short diagnostic label
operation_kind	Semantic operation	Required for mutate. For example, insert-text
paragraph_index	The paragraph number the edit applies to	Required for mutate. Zero-based numbering
offset	The edit’s position within the paragraph	Optional, defaults to 0. Counted in characters, not bytes or UTF-16 units
text	The text to insert	Needed by every kind that inserts something. Without it, the insertion does nothing
delete_count	How many characters to delete	Optional, defaults to 0 — so a delete without this field successfully deletes nothing. Needed by delete-text and replace-text

Response format

Success:

{"id":"ping-1","ok":true,"cmd":"ping","elapsed_ms":0,"result":{"pong":true}}

Refusal:

{"id":"bad-1","ok":false,"cmd":"mutate","elapsed_ms":0,"error":"..."}

Error handling

The response arriving doesn’t mean the command succeeded: those are different things. Always check ok === true; when it’s false, log id, cmd, and error in your integration log.

error is a reason in words, not a code: don’t branch your handling on it, the wording changes along with the message. Distinguish cases by command and by outcome, and show the text itself to the user and write it to the log. A stable list of errors is one of the things locked in before integration begins. If you’re also embedding spreadsheets, don’t carry over the habit from SumSheet: there, a refusal has a separate code field; here it doesn’t.

For mutate, ok alone isn’t enough. An edit the core didn’t accept — say, with an unknown operation_kind — still returns ok: true, and the outcome is named in the result.mutation.result_kind field. Check it too: otherwise an unaccepted edit will look successful, the document will stay unchanged, and you won’t find out.

The rule is simple: only applied changed the document. Every other outcome means it didn’t, and they differ only in the reason.

Outcome	What happened
applied	The edit was applied. This is the only case where the document changed.
invalid-request	The request itself is invalid: an unknown operation kind, inconsistent fields.
invalid-target	The request is understood, but points to the wrong place — that edit can’t be made at that address.
not-found	What was referenced isn’t in the document.
deferred	The operation’s condition wasn’t unambiguously satisfied — for example, it needed exactly one matching field, but found a different number of them. The core doesn’t treat this as a request error and changes nothing.

Checking for equality with applied is more reliable than enumerating refusals: there are more than two outcomes, and comparing against just invalid-request will miss the other three.

Response contents

Field	When it’s present	What it means
id	always	The request’s tag, returned unchanged. Equal to null if the request didn’t carry one or couldn’t be parsed.
ok	always	true — the command succeeded, false — it was refused.
cmd	almost always	The command name. Absent from the response to shutdown and on a request parse error — in that case, the command name is unknown.
elapsed_ms	almost always	Processing time. Absent from the response to shutdown.
result	when ok: true	The command’s result.
error	when ok: false	A string with the reason for the refusal.
result.mutation.result_kind	in the response to mutate	The edit’s outcome. Only applied changed the document; invalid-request, invalid-target, not-found, and deferred mean it didn’t. The envelope still stays ok: true.
shutdown	in the response to shutdown	true. A sign the session is closing: no fields other than id and ok arrive in this response.

When parsing a response, don’t treat cmd and elapsed_ms as required: they’re absent on session shutdown and on an unparsed request.

Edit order isn’t always checked

How strict the check is depends on whether you named the document when opening it.

With document_id. Every edit must carry a transaction_order equal to the previous one plus one. Skip a number or repeat one, and you’ll get the refusal “out-of-order history transaction: expected 2, received 1”, and the document won’t change. If an edit’s document_id doesn’t match the one from open, you get a different refusal: “stale document identity: expected …, received …”.

Without document_id. The order isn’t checked at all: 0 is replaced with the next number in sequence, and any other number is accepted as is. A mismatch between your count and the core’s history will go unnoticed.

Hence the advice to name the document when opening it: strict checking is what turns desync into an explicit refusal instead of a silent mismatch.

The operation_kind values

Paragraph text editing accepts eight kinds: insert-text and delete-text, their tracked-changes variants insert-text-tracked and delete-text-tracked, split-paragraph and merge-with-next for splitting and joining paragraphs, insert-line-break and delete-line-break for line breaks. The replace-text kind is accepted too: the core splits it itself into a delete and an insert — as one history entry, not two.

It’s the only one that responds to an incomplete request with an envelope refusal rather than an edit outcome: without delete_count or without text you’ll get ok: false with the reason “replace-text requires a non-empty delete range and insertion”. The other kinds respond ok: true in the same situation and change nothing.

Formatting a selection uses the same requests with different kinds: set-bold, set-italic, set-underline, set-font-family, set-font-size, set-font-color, set-text-highlight, set-strikethrough, and other character properties.

For complex changes, the apply-text-transaction command is meant to replace mutate — see Typed edit types.