Documents

​
Comment on words of an in-house Space document, or reply in a thread

A thread anchors on words: parent: {object: "node", anchor: {kind: "find", text: "<3–6 words exactly as written>", nth?, parent_id?}}; without anchor it is a note on the whole document. One mark of a chart or one box of a diagram: anchor: {kind: "element", block_id: "<block id>", element: "datum:<x>" | "datum:<x>|<series>" | "node:<id>"} (element_none when it is not there). A reply names the thread: parent: {object: "utterance", id: "<thread id>"}. to: ["agent"] sends it to the agent. Limits: 1000 threads a document (resolved ones count), 100 comments a thread, 4096-byte bodies (too_many, row_too_large; nothing written).

POST
/v1/space/documents/{document_id}/comments
curl -X POST "https://api.orchestor.io/v1/space/documents/%3Cdocument_id%3E/comments" \  -H "Authorization: Bearer $API_KEY" \  -H "X-Workspace-ID: wks_abc123" \  -H "Content-Type: application/json" \  -d '{  "body": "string",  "parent": {    "object": "node"  },  "to": []}'
{  "data": {    "actor": {      "id": "<string>",      "name": "<string>",      "type": "<string>"    },    "answered": true,    "body": "<string>",    "created_at": "2026-01-01T00:00:00Z",    "document_id": "<string>",    "edits": [      0    ],    "id": "<string>",    "kind": "comment",    "parent": {      "anchor": {        "block_id": "<string>",        "detached": true,        "element": null,        "end": "<string>",        "start": "<string>",        "text": "<string>"      },      "id": "<string>",      "object": "node"    },    "resolved": true,    "seq": 0,    "to": [      "agent"    ],    "updated_at": "2026-01-01T00:00:00Z",    "workspace_id": "<string>"  }}

Get your Orchestor API key

Create an API key in your workspace settings.

Authorizations

Satisfy one of these options:

  • Session cookie
  • API key

Authentication details

cookie
wos-session

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.

Path Parameters

document_idstringpathrequired
Pattern
^doc_[a-f0-9]{24}$

Headers

X-Workspace-IDstringheader

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.

Example"wks_abc123"

Bodyapplication/jsonrequired

Additional properties
Not allowed
bodystringbodyrequired
String length
≥ 1, ≤ 100000
parentobject | objectbodydefault:{"object":"node"}

Match exactly one of the following

Variant 1: object

Additional properties
Not allowed
parent.anchorobject | object | objectbody

Match exactly one of the following

Variant 1: object

Additional properties
Not allowed
parent.anchor.kindstringenum<string>bodyrequired
Allowed
find
parent.anchor.nthintegerbody
Value range
≥ 1
parent.anchor.parent_idstringbody
Pattern
^\d+\.\d+$
parent.anchor.textstringbodyrequired
String length
≥ 1, ≤ 2000

Variant 2: object

Additional properties
Not allowed
parent.anchor.endstringbodyrequired
String length
≥ 1, ≤ 512
parent.anchor.kindstringenum<string>bodyrequired
Allowed
range
parent.anchor.startstringbodyrequired
String length
≥ 1, ≤ 512
parent.anchor.textstringbodyrequired
String length
≥ 1, ≤ 2000

Variant 3: object

Additional properties
Not allowed
parent.anchor.block_idstringbodyrequired
Pattern
^\d+\.\d+$
parent.anchor.elementstringbodyrequired
String length
≥ 1, ≤ 512
parent.anchor.kindstringenum<string>bodyrequired
Allowed
element
parent.idstringbody
parent.objectstringenum<string>bodyrequired
Allowed
node

Variant 2: object

Additional properties
Not allowed
parent.idstringbodyrequired
Pattern
^dcm_[a-f0-9]{24}$
parent.objectstringenum<string>bodyrequired
Allowed
utterance
tostring[]bodydefault:[]
Item count
≤ 1
to[]stringenum<string>body
Allowed
agent

Response

application/json

Created comment

dataSpaceDocumentCommentrequired
data.actorobjectrequired
data.actor.idstring | nullrequired
data.actor.namestring | nullrequired
data.actor.typestringrequired
data.answeredbooleanrequired
data.bodystringrequired
data.created_atstringrequiredformat:date-time
data.document_idstringrequired
data.editsinteger[]required
data.edits[]integer
data.idstringrequired
data.kindstringenum<string>required
Allowed
commentresolvereopen
data.parentobject | objectrequired

Match exactly one of the following

Variant 1: object

data.parent.anchorobject | nullrequired
data.parent.anchor.block_idstring | nullrequired
data.parent.anchor.detachedbooleanrequired
data.parent.anchor.elementstring | nulldefault:null
data.parent.anchor.endstring | nullrequired
data.parent.anchor.startstring | nullrequired
data.parent.anchor.textstringrequired
data.parent.idstringrequired
data.parent.objectstringenum<string>required
Allowed
node

Variant 2: object

data.parent.idstringrequired
data.parent.objectstringenum<string>required
Allowed
utterance
data.resolvedbooleanrequired
data.seqintegerrequired
data.tostring[]required
data.to[]stringenum<string>
Allowed
agent
data.updated_atstringrequiredformat:date-time
data.workspace_idstringrequired