Enhance documentation
comment.start
Start a comment thread anchored to a canvas location.
comment.start
mutation write
Use when the requested change exactly matches comment.start; read the current state first when a version or identifier may have changed.
Before calling
- Authenticate as the accountable Enhance person.
- Use only resource identifiers returned by an earlier capability result or supplied by the person.
- Reuse clientToken only when retrying this exact mutation input.
Input
Show complete JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"canvasId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"clientThreadId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"anchor": {
"oneOf": [
{
"type": "object",
"properties": {
"on": {
"type": "string",
"const": "canvas"
},
"point": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
}
},
"required": [
"on",
"point"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"on": {
"type": "string",
"const": "node"
},
"nodeId": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"point": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
},
"element": {
"type": "null"
}
},
"required": [
"on",
"nodeId",
"point",
"element"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"on": {
"type": "string",
"const": "screen"
},
"nodeId": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"screenId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"point": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
},
"element": {
"anyOf": [
{
"type": "object",
"properties": {
"selector": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"tagName": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"label": {
"anyOf": [
{
"type": "string",
"maxLength": 80
},
{
"type": "null"
}
]
},
"source": {
"anyOf": [
{
"type": "object",
"properties": {
"file": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"line": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
}
},
"required": [
"file",
"line"
],
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"required": [
"selector",
"tagName",
"label",
"source"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"target": {
"oneOf": [
{
"type": "object",
"properties": {
"version": {
"type": "number",
"const": 1
},
"kind": {
"type": "string",
"const": "element"
},
"locator": {
"type": "object",
"properties": {
"selector": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"tagName": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"label": {
"anyOf": [
{
"type": "string",
"maxLength": 80
},
{
"type": "null"
}
]
},
"source": {
"anyOf": [
{
"type": "object",
"properties": {
"file": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"line": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
}
},
"required": [
"file",
"line"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"role": {
"type": "string",
"minLength": 1,
"maxLength": 80
}
},
"required": [
"selector",
"tagName",
"label",
"source"
],
"additionalProperties": false
},
"attachment": {
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"y": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
},
"fallbackBounds": {
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"y": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"width": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"height": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
}
},
"required": [
"version",
"kind",
"locator",
"attachment",
"fallbackBounds"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"version": {
"type": "number",
"const": 1
},
"kind": {
"type": "string",
"const": "text"
},
"root": {
"type": "object",
"properties": {
"selector": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"tagName": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"label": {
"anyOf": [
{
"type": "string",
"maxLength": 80
},
{
"type": "null"
}
]
},
"source": {
"anyOf": [
{
"type": "object",
"properties": {
"file": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"line": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
}
},
"required": [
"file",
"line"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"role": {
"type": "string",
"minLength": 1,
"maxLength": 80
}
},
"required": [
"selector",
"tagName",
"label",
"source"
],
"additionalProperties": false
},
"quote": {
"type": "object",
"properties": {
"exact": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"prefix": {
"type": "string",
"maxLength": 120
},
"suffix": {
"type": "string",
"maxLength": 120
}
},
"required": [
"exact",
"prefix",
"suffix"
],
"additionalProperties": false
},
"range": {
"type": "object",
"properties": {
"start": {
"type": "object",
"properties": {
"path": {
"maxItems": 64,
"type": "array",
"items": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"offset": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"path",
"offset"
],
"additionalProperties": false
},
"end": {
"type": "object",
"properties": {
"path": {
"maxItems": 64,
"type": "array",
"items": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"offset": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"path",
"offset"
],
"additionalProperties": false
}
},
"required": [
"start",
"end"
],
"additionalProperties": false
},
"attachment": {
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"y": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
},
"fallbackBounds": {
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"y": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"width": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"height": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
}
},
"required": [
"version",
"kind",
"root",
"quote",
"range",
"attachment",
"fallbackBounds"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"version": {
"type": "number",
"const": 1
},
"kind": {
"type": "string",
"const": "elements"
},
"members": {
"minItems": 2,
"maxItems": 32,
"type": "array",
"items": {
"type": "object",
"properties": {
"selector": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"tagName": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"label": {
"anyOf": [
{
"type": "string",
"maxLength": 80
},
{
"type": "null"
}
]
},
"source": {
"anyOf": [
{
"type": "object",
"properties": {
"file": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"line": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
}
},
"required": [
"file",
"line"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"role": {
"type": "string",
"minLength": 1,
"maxLength": 80
}
},
"required": [
"selector",
"tagName",
"label",
"source"
],
"additionalProperties": false
}
},
"truncated": {
"type": "boolean"
},
"attachment": {
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"y": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
},
"fallbackBounds": {
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"y": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"width": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"height": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
}
},
"required": [
"version",
"kind",
"members",
"truncated",
"attachment",
"fallbackBounds"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"version": {
"type": "number",
"const": 1
},
"kind": {
"type": "string",
"const": "area"
},
"bounds": {
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"y": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"width": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"height": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"x",
"y",
"width",
"height"
],
"additionalProperties": false
},
"attachment": {
"type": "object",
"properties": {
"x": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"y": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
}
},
"required": [
"version",
"kind",
"bounds",
"attachment"
],
"additionalProperties": false
}
]
}
},
"required": [
"on",
"nodeId",
"screenId",
"point",
"element"
],
"additionalProperties": false
}
]
},
"body": {
"type": "string",
"minLength": 1,
"maxLength": 10000
},
"mentionedPersonIds": {
"default": [],
"maxItems": 10,
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
}
},
"required": [
"canvasId",
"clientThreadId",
"anchor",
"body",
"mentionedPersonIds"
],
"additionalProperties": false
}Example
Show example input
{
"canvasId": "00000000-0000-4000-8000-000000000010",
"clientThreadId": "00000000-0000-4000-8000-000000000010",
"anchor": {
"on": "canvas",
"point": {
"x": 0,
"y": 0
}
},
"body": "x",
"mentionedPersonIds": []
}Result
Returns a typed comment.start result from the Enhance API without transport-specific prose.
Recovery
- BAD_REQUEST: correct the named fields and call again.
- UNAUTHORIZED: restore Enhance authentication, then retry once.
- FORBIDDEN or NOT_FOUND: list accessible resources and choose an allowed identifier.
- CONFLICT: read the current resource, merge the intended change, and retry with its version.
- INTERNAL: run Enhance diagnostics, report the failure, and stop repeating the call.
Continue with
- Read the affected comment resource to confirm the result.
Compatibility: 7097b0e2e710e1282d5cae604ce695e1b22d17d7934c189ada942aff9b586e50.