--- title: Edit an in-house Space document by block id or quoted words with prose ops (insert, replace, delete, move, set, restore), guarded by block hash and revision description: "Edit a Space document with prose ops, applied in order and all-or-nothing on the latest version (text people type meanwhile is kept). Ops: insert {target, side, source} · replace {target, with} · delete {target} · move {target, to:{target, side}} · set {target, attrs:{kind|checked|background|rows|spec|caption}} · restore {rev} (the only op in its call, with payload.ifRev = the latest rev). Targets: {\"kind\":\"find\",\"text\":\"…\",\"nth\"?} words as they stand · {\"kind\":\"blocks\",\"ids\":[…]} full ids off a read or ack · {\"kind\":\"root\"} with side start/end · {\"kind\":\"cell\",\"table\",\"row\",\"col\"}. source/with = {\"from\":{\"kind\":\"inline\",\"content\":…},\"as\":\"text\"|\"markdown\"|\"\ blocks\"}: text re-words in place keeping formatting; markdown re-creates blocks; blocks is a JSON node tree (table rows: [{\"type\":\"row\",\"content\":[{\"type\":\"cell\",…}]}]). A pending block is filled by replacing its id with \"## Heading\" + body (no guard); later edits use the ids in that ack. A whole-block replace/delete carries \"ifHash\" (its newest h) and \"ifRev\" (the rev of the read that showed it); several ids or a cell take \"ifRev\"; \"force\" only when told to overwrite. side \"end\" on a heading id = end of its section; on a list/table/row id = append inside it. set: list kind bullet|ordered|check, checked on a check-list item, cell background one of #f0efec #fbebeb #f9ece7 #f9eeda #e5f4e4 #e7f1fb #efedff (null clears). Column: insert with \"each\":true at every row id. Charts and diagrams: a chart block is drawn from rows + spec, never a picture; a diagram block from boxes + connectors. Place one with the embed chip + blocks {\"chart\":{\"type\":\"chart\",\"spec\":{…},\"rows\":[…],\"caption\":\"…\"}} (or \"type\":\"diagram\"); change it with set attrs {rows|spec|caption} on its id. Chips: put in the markdown and the chip in \"blocks\": mention {\"user\":\"me\"} (the requesting user), an existing member's user id, or an email only when the user named it — never guess one; mention {\"ref\":\"project/\"} links another document; date {\"value\":\"YYYY-MM-DD\"} for actionable dates only. Only members and documents of this workspace resolve. Images and files: create a blob first (create_space_document_blob), then insert its markdown (![alt](blob/)); a blob/ of another workspace is refused. A refusal writes nothing: 409 with error.code (guard_mismatch: the block changed, error.data shows it as it stands, redo from it and never force; find_none: re-read and quote what it says now; block_gone: someone removed it, never re-create it; missing_guard, cell_none, last_block, same_anchor, place_arity, shape, bad_request) and error.param (the op path)." canonical_url: https://orchestor.io/docs/en/space/rest-api/endpoint-reference/documents/post-edit-space-document markdown_url: https://orchestor.io/docs/en/space/rest-api/endpoint-reference/documents/post-edit-space-document.md --- # Edit an in-house Space document by block id or quoted words with prose ops (insert, replace, delete, move, set, restore), guarded by block hash and revision Edit a Space document with prose ops, applied in order and all-or-nothing on the latest version (text people type meanwhile is kept). Ops: insert {target, side, source} · replace {target, with} · delete {target} · move {target, to:{target, side}} · set {target, attrs:{kind|checked|background|rows|spec|caption}} · restore {rev} (the only op in its call, with payload.ifRev = the latest rev). Targets: {"kind":"find","text":"…","nth"?} words as they stand · {"kind":"blocks","ids":[…]} full ids off a read or ack · {"kind":"root"} with side start/end · {"kind":"cell","table","row","col"}. source/with = {"from":{"kind":"inline","content":…},"as":"text"|"markdown"|"blocks"}: text re-words in place keeping formatting; markdown re-creates blocks; blocks is a JSON node tree (table rows: [{"type":"row","content":[{"type":"cell",…}]}]). A pending block is filled by replacing its id with "## Heading" + body (no guard); later edits use the ids in that ack. A whole-block replace/delete carries "ifHash" (its newest h) and "ifRev" (the rev of the read that showed it); several ids or a cell take "ifRev"; "force" only when told to overwrite. side "end" on a heading id = end of its section; on a list/table/row id = append inside it. set: list kind bullet|ordered|check, checked on a check-list item, cell background one of #f0efec #fbebeb #f9ece7 #f9eeda #e5f4e4 #e7f1fb #efedff (null clears). Column: insert with "each":true at every row id. Charts and diagrams: a chart block is drawn from rows + spec, never a picture; a diagram block from boxes + connectors. Place one with the embed chip + blocks {"chart":{"type":"chart","spec":{…},"rows":[…],"caption":"…"}} (or "type":"diagram"); change it with set attrs {rows|spec|caption} on its id. Chips: put in the markdown and the chip in "blocks": mention {"user":"me"} (the requesting user), an existing member's user id, or an email only when the user named it — never guess one; mention {"ref":"project/"} links another document; date {"value":"YYYY-MM-DD"} for actionable dates only. Only members and documents of this workspace resolve. Images and files: create a blob first (create_space_document_blob), then insert its markdown (![alt](https://orchestor.io/docs/en/space/rest-api/endpoint-reference/documents/blob/%3Cid%3E)); a blob/ of another workspace is refused. A refusal writes nothing: 409 with error.code (guard_mismatch: the block changed, error.data shows it as it stands, redo from it and never force; find_none: re-read and quote what it says now; block_gone: someone removed it, never re-create it; missing_guard, cell_none, last_block, same_anchor, place_arity, shape, bad_request) and error.param (the op path). ```http POST /v1/space/documents/{document_id}/edit ``` Server: https://api.orchestor.io Operation ID: `editSpaceDocument` ## Authentication ```json [ [ { "key": "session_cookie", "type": "apiKey", "description": "Browser session established by signing in to the web app. The server checks your workspace membership and permissions. Supply X-Workspace-ID for workspace-scoped operations. For server-to-server requests, use an API key when the operation supports it.", "name": "wos-session", "in": "cookie", "scopes": [] } ], [ { "key": "bearer_api_key", "type": "http", "description": "Authenticate with a workspace-scoped API key using Authorization: Bearer . Supported key prefixes are sk_live_ and sk_test_. The key determines the workspace and allowed permissions; supplying X-Workspace-ID does not grant access to another workspace. Create and manage API keys in workspace settings. Never put a key in a URL.", "scheme": "bearer", "scopes": [] } ] ] ``` ## Parameters ```json [ { "name": "X-Workspace-ID", "in": "header", "required": false, "description": "Workspace to access. With a workspace-scoped API key, the server derives this value from the key, so the header is optional. If supplied, it must match the credential workspace or the request returns 403 workspace_mismatch. For interactive session requests, supply this header to select a workspace where you are a member. A project ID cannot be used as a workspace ID.", "schema": { "type": "string", "example": "wks_abc123" } }, { "name": "document_id", "in": "path", "required": true, "schema": { "pattern": "^doc_[a-f0-9]{24}$", "type": "string" } } ] ``` ## Request body ```json { "required": true, "content": [ { "contentType": "application/json", "schema": { "name": "SpaceDocumentOps", "type": "object", "required": [ "ops" ], "properties": { "answering": { "pattern": "^dcm_[a-f0-9]{24}$", "type": "string", "description": "The thread (its first comment id) this edit answers, when a comment asked for it." }, "ifRev": { "minimum": 0, "type": "integer" }, "ops": { "minItems": 1, "maxItems": 64, "type": "array", "items": { "anyOf": [ { "type": "object", "required": [ "op", "target", "side", "source" ], "properties": { "each": { "type": "boolean" }, "op": { "type": "string", "enumValues": [ "insert" ] }, "side": { "type": "string", "enumValues": [ "before", "after", "start", "end" ] }, "source": { "type": "object", "required": [ "from", "as" ], "properties": { "as": { "type": "string", "enumValues": [ "text", "markdown", "blocks" ] }, "blocks": { "type": "object", "description": "Chips for tokens in the markdown, e.g. {\"s1\":{\"type\":\"pending\",\"intent\":\"Risks: …\"}}, {\"me\":{\"type\":\"mention\",\"user\":\"me\"},\"due\":{\"type\":\"date\",\"value\":\"2026-11-01\"},\"plan\":{\"type\":\"mention\",\"ref\":\"project/doc_…\"}} or {\"chart\":{\"type\":\"chart\",\"spec\":{…},\"rows\":[…],\"caption\":\"\"}}.", "additionalProperties": { "anyOf": [ { "type": "object", "required": [ "type", "intent" ], "properties": { "intent": { "maxLength": 2000, "type": "string" }, "type": { "type": "string", "enumValues": [ "pending" ] } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enumValues": [ "paragraph" ] } } }, { "type": "object", "required": [ "type", "spec", "rows" ], "properties": { "caption": { "type": "string" }, "rows": { "maxItems": 2000, "type": "array", "description": "The rows the chart draws, as measured (≤ 2000 rows, 256 KiB).", "items": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } }, "spec": { "type": "object", "required": [ "kind", "title", "x", "y" ], "properties": { "kind": { "type": "string", "enumValues": [ "line", "bar", "pie" ] }, "series": { "type": "string", "description": "A column whose VALUES name the series: one row per series and period." }, "title": { "minLength": 1, "type": "string", "description": "The finding, with its number, not the topic." }, "unit": { "type": "string" }, "x": { "minLength": 1, "type": "string", "description": "The column along the axis (or the pie slices)." }, "y": { "minLength": 1, "type": "string", "description": "The measured column (numbers)." } } }, "type": { "type": "string", "enumValues": [ "chart" ] } } }, { "type": "object", "required": [ "type", "spec" ], "properties": { "caption": { "type": "string" }, "spec": { "type": "object", "required": [ "title", "direction", "nodes", "edges" ], "properties": { "direction": { "type": "string", "enumValues": [ "right", "down" ] }, "edges": { "maxItems": 120, "type": "array", "items": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string" }, "label": { "type": "string" }, "to": { "type": "string" } } } }, "nodes": { "minItems": 1, "maxItems": 60, "type": "array", "items": { "type": "object", "required": [ "id", "label" ], "properties": { "detail": { "type": "string" }, "id": { "pattern": "^[\\w-]{1,64}$", "type": "string" }, "label": { "minLength": 1, "type": "string" } } } }, "title": { "minLength": 1, "type": "string" } } }, "type": { "type": "string", "enumValues": [ "diagram" ] } } }, { "type": "object", "required": [ "type", "user" ], "properties": { "type": { "type": "string", "enumValues": [ "mention" ] }, "user": { "minLength": 1, "maxLength": 320, "type": "string" } } }, { "type": "object", "required": [ "type", "ref" ], "properties": { "ref": { "pattern": "^project\\/doc_[a-f0-9]{24}$", "type": "string" }, "type": { "type": "string", "enumValues": [ "mention" ] } } }, { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "enumValues": [ "date" ] }, "value": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" } } } ] } }, "from": { "type": "object", "required": [ "kind", "content" ], "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, { "type": "object", "additionalProperties": {} } ] }, "kind": { "type": "string", "enumValues": [ "inline" ] } } } } }, "target": { "anyOf": [ { "type": "object", "description": "Words exactly as they stand in your last read or ack; \"nth\" when they repeat (default 1).", "required": [ "kind", "text" ], "properties": { "kind": { "type": "string", "enumValues": [ "find" ] }, "nth": { "minimum": 1, "type": "integer" }, "text": { "minLength": 1, "type": "string" }, "within": { "type": "object", "description": "A table cell by position: 0 = first row (the header row) / first column, -1 = last.", "required": [ "kind", "table", "row", "col" ], "properties": { "col": { "type": "integer" }, "kind": { "type": "string", "enumValues": [ "cell" ] }, "row": { "type": "integer" }, "table": { "pattern": "^\\d+\\.\\d+$", "type": "string", "description": "A full block id as a read or ack prints it, e.g. \"1938274.12\"." } } } } }, { "type": "object", "required": [ "kind", "ids" ], "properties": { "ids": { "minItems": 1, "maxItems": 4096, "type": "array", "items": { "pattern": "^\\d+\\.\\d+$", "type": "string", "description": "A full block id as a read or ack prints it, e.g. \"1938274.12\"." } }, "kind": { "type": "string", "enumValues": [ "blocks" ] } } }, { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enumValues": [ "root" ] } } }, { "type": "object", "description": "A table cell by position: 0 = first row (the header row) / first column, -1 = last.", "required": [ "kind", "table", "row", "col" ], "properties": { "col": { "type": "integer" }, "kind": { "type": "string", "enumValues": [ "cell" ] }, "row": { "type": "integer" }, "table": { "pattern": "^\\d+\\.\\d+$", "type": "string", "description": "A full block id as a read or ack prints it, e.g. \"1938274.12\"." } } } ] } } }, { "type": "object", "required": [ "op", "target", "with" ], "properties": { "force": { "type": "boolean" }, "ifHash": { "pattern": "^[0-9a-f]{8}$", "type": "string" }, "ifRev": { "minimum": 0, "type": "integer" }, "op": { "type": "string", "enumValues": [ "replace" ] }, "target": { "anyOf": [ { "type": "object", "description": "Words exactly as they stand in your last read or ack; \"nth\" when they repeat (default 1).", "required": [ "kind", "text" ], "properties": { "kind": { "type": "string", "enumValues": [ "find" ] }, "nth": { "minimum": 1, "type": "integer" }, "text": { "minLength": 1, "type": "string" }, "within": { "type": "object", "description": "A table cell by position: 0 = first row (the header row) / first column, -1 = last.", "required": [ "kind", "table", "row", "col" ], "properties": { "col": { "type": "integer" }, "kind": { "type": "string", "enumValues": [ "cell" ] }, "row": { "type": "integer" }, "table": { "pattern": "^\\d+\\.\\d+$", "type": "string", "description": "A full block id as a read or ack prints it, e.g. \"1938274.12\"." } } } } }, { "type": "object", "required": [ "kind", "ids" ], "properties": { "ids": { "minItems": 1, "maxItems": 4096, "type": "array", "items": { "pattern": "^\\d+\\.\\d+$", "type": "string", "description": "A full block id as a read or ack prints it, e.g. \"1938274.12\"." } }, "kind": { "type": "string", "enumValues": [ "blocks" ] } } }, { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enumValues": [ "root" ] } } }, { "type": "object", "description": "A table cell by position: 0 = first row (the header row) / first column, -1 = last.", "required": [ "kind", "table", "row", "col" ], "properties": { "col": { "type": "integer" }, "kind": { "type": "string", "enumValues": [ "cell" ] }, "row": { "type": "integer" }, "table": { "pattern": "^\\d+\\.\\d+$", "type": "string", "description": "A full block id as a read or ack prints it, e.g. \"1938274.12\"." } } } ] }, "with": { "type": "object", "required": [ "from", "as" ], "properties": { "as": { "type": "string", "enumValues": [ "text", "markdown", "blocks" ] }, "blocks": { "type": "object", "description": "Chips for tokens in the markdown, e.g. {\"s1\":{\"type\":\"pending\",\"intent\":\"Risks: …\"}}, {\"me\":{\"type\":\"mention\",\"user\":\"me\"},\"due\":{\"type\":\"date\",\"value\":\"2026-11-01\"},\"plan\":{\"type\":\"mention\",\"ref\":\"project/doc_…\"}} or {\"chart\":{\"type\":\"chart\",\"spec\":{…},\"rows\":[…],\"caption\":\"\"}}.", "additionalProperties": { "anyOf": [ { "type": "object", "required": [ "type", "intent" ], "properties": { "intent": { "maxLength": 2000, "type": "string" }, "type": { "type": "string", "enumValues": [ "pending" ] } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enumValues": [ "paragraph" ] } } }, { "type": "object", "required": [ "type", "spec", "rows" ], "properties": { "caption": { "type": "string" }, "rows": { "maxItems": 2000, "type": "array", "description": "The rows the chart draws, as measured (≤ 2000 rows, 256 KiB).", "items": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } }, "spec": { "type": "object", "required": [ "kind", "title", "x", "y" ], "properties": { "kind": { "type": "string", "enumValues": [ "line", "bar", "pie" ] }, "series": { "type": "string", "description": "A column whose VALUES name the series: one row per series and period." }, "title": { "minLength": 1, "type": "string", "description": "The finding, with its number, not the topic." }, "unit": { "type": "string" }, "x": { "minLength": 1, "type": "string", "description": "The column along the axis (or the pie slices)." }, "y": { "minLength": 1, "type": "string", "description": "The measured column (numbers)." } } }, "type": { "type": "string", "enumValues": [ "chart" ] } } }, { "type": "object", "required": [ "type", "spec" ], "properties": { "caption": { "type": "string" }, "spec": { "type": "object", "required": [ "title", "direction", "nodes", "edges" ], "properties": { "direction": { "type": "string", "enumValues": [ "right", "down" ] }, "edges": { "maxItems": 120, "type": "array", "items": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string" }, "label": { "type": "string" }, "to": { "type": "string" } } } }, "nodes": { "minItems": 1, "maxItems": 60, "type": "array", "items": { "type": "object", "required": [ "id", "label" ], "properties": { "detail": { "type": "string" }, "id": { "pattern": "^[\\w-]{1,64}$", "type": "string" }, "label": { "minLength": 1, "type": "string" } } } }, "title": { "minLength": 1, "type": "string" } } }, "type": { "type": "string", "enumValues": [ "diagram" ] } } }, { "type": "object", "required": [ "type", "user" ], "properties": { "type": { "type": "string", "enumValues": [ "mention" ] }, "user": { "minLength": 1, "maxLength": 320, "type": "string" } } }, { "type": "object", "required": [ "type", "ref" ], "properties": { "ref": { "pattern": "^project\\/doc_[a-f0-9]{24}$", "type": "string" }, "type": { "type": "string", "enumValues": [ "mention" ] } } }, { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "enumValues": [ "date" ] }, "value": { "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string" } } } ] } }, "from": { "type": "object", "required": [ "kind", "content" ], "properties": { "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, { "type": "object", "additionalProperties": {} } ] }, "kind": { "type": "string", "enumValues": [ "inline" ] } } } } } } }, { "type": "object", "required": [ "op", "target" ], "properties": { "force": { "type": "boolean" }, "ifHash": { "pattern": "^[0-9a-f]{8}$", "type": "string" }, "ifRev": { "minimum": 0, "type": "integer" }, "op": { "type": "string", "enumValues": [ "delete" ] }, "target": { "anyOf": [ { "type": "object", "description": "Words exactly as they stand in your last read or ack; \"nth\" when they repeat (default 1).", "required": [ "kind", "text" ], "properties": { "kind": { "type": "string", "enumValues": [ "find" ] }, "nth": { "minimum": 1, "type": "integer" }, "text": { "minLength": 1, "type": "string" }, "within": { "type": "object", "description": "A table cell by position: 0 = first row (the header row) / first column, -1 = last.", "required": [ "kind", "table", "row", "col" ], "properties": { "col": { "type": "integer" }, "kind": { "type": "string", "enumValues": [ "cell" ] }, "row": { "type": "integer" }, "table": { "pattern": "^\\d+\\.\\d+$", "type": "string", "description": "A full block id as a read or ack prints it, e.g. \"1938274.12\"." } } } } }, { "type": "object", "required": [ "kind", "ids" ], "properties": { "ids": { "minItems": 1, "maxItems": 4096, "type": "array", "items": { "pattern": "^\\d+\\.\\d+$", "type": "string", "description": "A full block id as a read or ack prints it, e.g. \"1938274.12\"." } }, "kind": { "type": "string", "enumValues": [ "blocks" ] } } }, { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enumValues": [ "root" ] } } }, { "type": "object", "description": "A table cell by position: 0 = first row (the header row) / first column, -1 = last.", "required": [ "kind", "table", "row", "col" ], "properties": { "col": { "type": "integer" }, "kind": { "type": "string", "enumValues": [ "cell" ] }, "row": { "type": "integer" }, "table": { "pattern": "^\\d+\\.\\d+$", "type": "string", "description": "A full block id as a read or ack prints it, e.g. \"1938274.12\"." } } } ] } } }, { "type": "object", "required": [ "op", "target", "to" ], "properties": { "op": { "type": "string", "enumValues": [ "move" ] }, "target": { "type": "object", "required": [ "kind", "ids" ], "properties": { "ids": { "minItems": 1, "maxItems": 4096, "type": "array", "items": { "pattern": "^\\d+\\.\\d+$", "type": "string", "description": "A full block id as a read or ack prints it, e.g. \"1938274.12\"." } }, "kind": { "type": "string", "enumValues": [ "blocks" ] } } }, "to": { "type": "object", "required": [ "target", "side" ], "properties": { "side": { "type": "string", "enumValues": [ "before", "after", "start", "end" ] }, "target": { "anyOf": [ { "type": "object", "required": [ "kind", "ids" ], "properties": { "ids": { "minItems": 1, "maxItems": 4096, "type": "array", "items": { "pattern": "^\\d+\\.\\d+$", "type": "string", "description": "A full block id as a read or ack prints it, e.g. \"1938274.12\"." } }, "kind": { "type": "string", "enumValues": [ "blocks" ] } } }, { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enumValues": [ "root" ] } } } ] } } } } }, { "type": "object", "required": [ "op", "target", "attrs" ], "properties": { "attrs": { "type": "object", "properties": { "background": { "type": "string", "nullable": true }, "caption": { "type": "string" }, "checked": { "type": "boolean" }, "kind": { "type": "string", "enumValues": [ "bullet", "ordered", "check" ] }, "rows": { "maxItems": 2000, "type": "array", "description": "The rows the chart draws, as measured (≤ 2000 rows, 256 KiB).", "items": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } }, "spec": { "anyOf": [ { "type": "object", "required": [ "kind", "title", "x", "y" ], "properties": { "kind": { "type": "string", "enumValues": [ "line", "bar", "pie" ] }, "series": { "type": "string", "description": "A column whose VALUES name the series: one row per series and period." }, "title": { "minLength": 1, "type": "string", "description": "The finding, with its number, not the topic." }, "unit": { "type": "string" }, "x": { "minLength": 1, "type": "string", "description": "The column along the axis (or the pie slices)." }, "y": { "minLength": 1, "type": "string", "description": "The measured column (numbers)." } } }, { "type": "object", "required": [ "title", "direction", "nodes", "edges" ], "properties": { "direction": { "type": "string", "enumValues": [ "right", "down" ] }, "edges": { "maxItems": 120, "type": "array", "items": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string" }, "label": { "type": "string" }, "to": { "type": "string" } } } }, "nodes": { "minItems": 1, "maxItems": 60, "type": "array", "items": { "type": "object", "required": [ "id", "label" ], "properties": { "detail": { "type": "string" }, "id": { "pattern": "^[\\w-]{1,64}$", "type": "string" }, "label": { "minLength": 1, "type": "string" } } } }, "title": { "minLength": 1, "type": "string" } } } ] } } }, "op": { "type": "string", "enumValues": [ "set" ] }, "target": { "anyOf": [ { "type": "object", "required": [ "kind", "ids" ], "properties": { "ids": { "minItems": 1, "maxItems": 4096, "type": "array", "items": { "pattern": "^\\d+\\.\\d+$", "type": "string", "description": "A full block id as a read or ack prints it, e.g. \"1938274.12\"." } }, "kind": { "type": "string", "enumValues": [ "blocks" ] } } }, { "type": "object", "description": "A table cell by position: 0 = first row (the header row) / first column, -1 = last.", "required": [ "kind", "table", "row", "col" ], "properties": { "col": { "type": "integer" }, "kind": { "type": "string", "enumValues": [ "cell" ] }, "row": { "type": "integer" }, "table": { "pattern": "^\\d+\\.\\d+$", "type": "string", "description": "A full block id as a read or ack prints it, e.g. \"1938274.12\"." } } } ] } } }, { "type": "object", "required": [ "op", "rev" ], "properties": { "op": { "type": "string", "enumValues": [ "restore" ] }, "rev": { "minimum": 1, "type": "integer" } } } ] } } } } } ] } ``` ## Responses ### 200 ```json { "statusCode": "200", "description": "What each op wrote, as a read prints it, and the new revision", "headers": [], "content": [ { "contentType": "application/json", "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "name": "SpaceDocumentEditAck", "type": "object", "required": [ "rev", "ops" ], "properties": { "ops": { "type": "array", "items": { "type": "object", "required": [ "op", "xml" ], "properties": { "notices": { "type": "array", "items": { "type": "string" } }, "op": { "type": "string" }, "xml": { "type": "string" } } } }, "rev": { "type": "integer" } } } } } } ] } ``` ### 400 ```json { "statusCode": "400", "description": "Invalid request parameters or body. Not retryable — fix the request before retrying.\nCommon error codes: `invalid_parameter` (wrong type or out of range),\n`missing_required_field` (a required body field is absent),\n`invalid_json` (request body is not valid JSON),\n`validation_error` (field fails schema validation, e.g., URL format or enum value).\n", "headers": [], "content": [ { "contentType": "application/json", "schema": { "name": "ApiError", "type": "object", "description": "Common structured error envelope. Use the HTTP status and error code to handle failures. Some endpoints declare more specific error schemas with additional fields.", "required": [ "error" ], "properties": { "error": { "type": "object", "description": "Failure category, code and human-readable explanation, with optional field or validation context.", "required": [ "type", "code", "message", "doc_url" ], "properties": { "type": { "type": "string", "description": "Broad error category for classifying the failure. The more specific code and HTTP status determine how to handle it.", "enumValues": [ "invalid_request_error", "authentication_error", "permission_error", "entitlement_error", "not_found_error", "rate_limit_error", "api_error" ] }, "code": { "type": "string", "description": "Machine-readable failure code. Preserve its case when matching it; handlers may return uppercase codes such as VALIDATION_ERROR or lowercase codes such as invalid_parameter. New codes may be added; supported codes depend on the endpoint.", "example": "VALIDATION_ERROR" }, "message": { "type": "string", "description": "Human-readable explanation of this failure. Wording can vary; use code rather than parsing this text for programmatic decisions.", "example": "Request validation failed" }, "feature": { "type": "string", "description": "Entitlement capability required for a 402 denial.", "example": "included_engines" }, "upgrade_url": { "type": "string", "format": "uri", "description": "Plan or grant recovery destination supplied with a 402 denial." }, "param": { "type": "string", "description": "Input field or parameter associated with the error, when supplied by the handler. Omitted when no single parameter is identified; validation failures may instead provide several entries in details.", "example": "limit" }, "doc_url": { "type": "string", "format": "uri", "description": "Documentation URL supplied with the error. Use the returned URL instead of constructing it from code; URL formatting can differ between handlers.", "example": "https://docs.orchestor.io/errors/validation_error" }, "details": { "description": "Additional failure context when supplied. Validation middleware returns an array of field issues; typed business errors return a code-specific object. Omission means no additional context was attached.", "anyOf": [ { "type": "array", "description": "Validation issues. A request can have multiple issues, including more than one for the same field.", "example": [ { "path": "items.0.name", "message": "Invalid input", "code": "invalid_type" } ], "items": { "type": "object", "required": [ "path", "message", "code" ], "properties": { "path": { "type": "string", "description": "Dot-separated path to the invalid value, including array indexes. An empty string identifies the root input.", "example": "items.0.name" }, "message": { "type": "string", "description": "Human-readable explanation of this validation issue. Use code and path for programmatic handling.", "example": "Invalid input" }, "code": { "type": "string", "description": "Validation issue code, such as invalid_type, or a custom code provided by the validator. It is distinct from the outer error.code.", "example": "invalid_type" } } } }, { "type": "object", "description": "Additional fields specific to the error code. Consult the endpoint's error documentation before interpreting them.", "additionalProperties": true } ] } } } } }, "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "limit must be between 1 and 200", "param": "limit", "doc_url": "https://docs.orchestor.io/api-reference/errors#invalid-request" } } } ] } ``` ### 401 ```json { "statusCode": "401", "description": "Authentication required or credentials invalid. Not retryable without new credentials.\nCommon error codes: `invalid_api_key` (key is missing, malformed, or revoked),\n`expired_session` (session cookie expired — re-authenticate via the web app).\n", "headers": [], "content": [ { "contentType": "application/json", "schema": { "name": "ApiError", "type": "object", "description": "Common structured error envelope. Use the HTTP status and error code to handle failures. Some endpoints declare more specific error schemas with additional fields.", "required": [ "error" ], "properties": { "error": { "type": "object", "description": "Failure category, code and human-readable explanation, with optional field or validation context.", "required": [ "type", "code", "message", "doc_url" ], "properties": { "type": { "type": "string", "description": "Broad error category for classifying the failure. The more specific code and HTTP status determine how to handle it.", "enumValues": [ "invalid_request_error", "authentication_error", "permission_error", "entitlement_error", "not_found_error", "rate_limit_error", "api_error" ] }, "code": { "type": "string", "description": "Machine-readable failure code. Preserve its case when matching it; handlers may return uppercase codes such as VALIDATION_ERROR or lowercase codes such as invalid_parameter. New codes may be added; supported codes depend on the endpoint.", "example": "VALIDATION_ERROR" }, "message": { "type": "string", "description": "Human-readable explanation of this failure. Wording can vary; use code rather than parsing this text for programmatic decisions.", "example": "Request validation failed" }, "feature": { "type": "string", "description": "Entitlement capability required for a 402 denial.", "example": "included_engines" }, "upgrade_url": { "type": "string", "format": "uri", "description": "Plan or grant recovery destination supplied with a 402 denial." }, "param": { "type": "string", "description": "Input field or parameter associated with the error, when supplied by the handler. Omitted when no single parameter is identified; validation failures may instead provide several entries in details.", "example": "limit" }, "doc_url": { "type": "string", "format": "uri", "description": "Documentation URL supplied with the error. Use the returned URL instead of constructing it from code; URL formatting can differ between handlers.", "example": "https://docs.orchestor.io/errors/validation_error" }, "details": { "description": "Additional failure context when supplied. Validation middleware returns an array of field issues; typed business errors return a code-specific object. Omission means no additional context was attached.", "anyOf": [ { "type": "array", "description": "Validation issues. A request can have multiple issues, including more than one for the same field.", "example": [ { "path": "items.0.name", "message": "Invalid input", "code": "invalid_type" } ], "items": { "type": "object", "required": [ "path", "message", "code" ], "properties": { "path": { "type": "string", "description": "Dot-separated path to the invalid value, including array indexes. An empty string identifies the root input.", "example": "items.0.name" }, "message": { "type": "string", "description": "Human-readable explanation of this validation issue. Use code and path for programmatic handling.", "example": "Invalid input" }, "code": { "type": "string", "description": "Validation issue code, such as invalid_type, or a custom code provided by the validator. It is distinct from the outer error.code.", "example": "invalid_type" } } } }, { "type": "object", "description": "Additional fields specific to the error code. Consult the endpoint's error documentation before interpreting them.", "additionalProperties": true } ] } } } } }, "example": { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "Invalid API key provided", "doc_url": "https://docs.orchestor.io/api-reference/errors#authentication" } } } ] } ``` ### 404 ```json { "statusCode": "404", "description": "The requested resource is unavailable in the current workspace or route scope. Check the identifier and selected workspace. The same response can be returned for a deleted resource or a resource outside your access scope.", "headers": [], "content": [ { "contentType": "application/json", "schema": { "name": "ApiError", "type": "object", "description": "Common structured error envelope. Use the HTTP status and error code to handle failures. Some endpoints declare more specific error schemas with additional fields.", "required": [ "error" ], "properties": { "error": { "type": "object", "description": "Failure category, code and human-readable explanation, with optional field or validation context.", "required": [ "type", "code", "message", "doc_url" ], "properties": { "type": { "type": "string", "description": "Broad error category for classifying the failure. The more specific code and HTTP status determine how to handle it.", "enumValues": [ "invalid_request_error", "authentication_error", "permission_error", "entitlement_error", "not_found_error", "rate_limit_error", "api_error" ] }, "code": { "type": "string", "description": "Machine-readable failure code. Preserve its case when matching it; handlers may return uppercase codes such as VALIDATION_ERROR or lowercase codes such as invalid_parameter. New codes may be added; supported codes depend on the endpoint.", "example": "VALIDATION_ERROR" }, "message": { "type": "string", "description": "Human-readable explanation of this failure. Wording can vary; use code rather than parsing this text for programmatic decisions.", "example": "Request validation failed" }, "feature": { "type": "string", "description": "Entitlement capability required for a 402 denial.", "example": "included_engines" }, "upgrade_url": { "type": "string", "format": "uri", "description": "Plan or grant recovery destination supplied with a 402 denial." }, "param": { "type": "string", "description": "Input field or parameter associated with the error, when supplied by the handler. Omitted when no single parameter is identified; validation failures may instead provide several entries in details.", "example": "limit" }, "doc_url": { "type": "string", "format": "uri", "description": "Documentation URL supplied with the error. Use the returned URL instead of constructing it from code; URL formatting can differ between handlers.", "example": "https://docs.orchestor.io/errors/validation_error" }, "details": { "description": "Additional failure context when supplied. Validation middleware returns an array of field issues; typed business errors return a code-specific object. Omission means no additional context was attached.", "anyOf": [ { "type": "array", "description": "Validation issues. A request can have multiple issues, including more than one for the same field.", "example": [ { "path": "items.0.name", "message": "Invalid input", "code": "invalid_type" } ], "items": { "type": "object", "required": [ "path", "message", "code" ], "properties": { "path": { "type": "string", "description": "Dot-separated path to the invalid value, including array indexes. An empty string identifies the root input.", "example": "items.0.name" }, "message": { "type": "string", "description": "Human-readable explanation of this validation issue. Use code and path for programmatic handling.", "example": "Invalid input" }, "code": { "type": "string", "description": "Validation issue code, such as invalid_type, or a custom code provided by the validator. It is distinct from the outer error.code.", "example": "invalid_type" } } } }, { "type": "object", "description": "Additional fields specific to the error code. Consult the endpoint's error documentation before interpreting them.", "additionalProperties": true } ] } } } } }, "example": { "error": { "type": "not_found_error", "code": "resource_not_found", "message": "Resource not found", "doc_url": "https://docs.orchestor.io/api-reference/errors#not-found" } } } ] } ``` ### 409 ```json { "statusCode": "409", "description": "Refused: nothing was written. error.code names the refusal (guard_mismatch, find_none, block_gone, missing_guard, cell_none, last_block, same_anchor, place_arity, shape, bad_request), error.param the op path, and error.data the block as it stands.", "headers": [], "content": [] } ``` --- [Documentation index](https://orchestor.io/docs/llms.txt)