Skip to main content
POST
Start a thread

Authorizations

scribe_session
string
cookie
required

Browser session cookie set by the WorkOS sign-in flow.

Path Parameters

id
string
required

Id of the document to start the thread on.

Body

application/json

The thread kind, anchor (anchorJson or quotedText), and first message.

Start a new comment or suggestion thread.

kind
enum<string>
required

Kind of thread to start: comment or suggestion.

Available options:
comment,
suggestion
Example:

"comment"

anchorJson
string

Serialized Yjs relative positions ({from,to}) for the selection. Produced by the editor; API callers that cannot compute relative positions should instead anchor by quotedText and omit this. Provide anchorJson or quotedText (anchorJson wins when both are given).

Minimum string length: 1
Example:

"{\"from\":{\"type\":\"relative\",\"item\":10},\"to\":{\"type\":\"relative\",\"item\":24}}"

quotedText
string

Text selected when creating the thread. When anchorJson is omitted, the server locates this exact text in the current document (first occurrence) and computes the anchor for you — the way an API caller or agent anchors a comment without a live editor. 422 quote_not_found when the text is not present.

Minimum string length: 1
Example:

"ship in Q2"

proposedText
string

Replacement text for a legacy replacement suggestion. Required when kind is suggestion and no sid is given; must be omitted for sid (suggesting-mode) suggestions.

Example:

"ship in Q3"

sid
string

Suggesting-mode suggestion id: ties the thread to an existing suggestion_insert/suggestion_delete mark burst in the collaborative document (created by the editor). Suggestions only.

Minimum string length: 1
Example:

"sug_lx2c1a9k3f0d"

body
string

First message of the thread. Required for comments and legacy replacement suggestions; optional for suggesting-mode (sid) suggestions, which are auto-created without a note.

Required string length: 1 - 10000
Example:

"Should this say Q3 instead of Q2?"

Response

The created thread with its first message.

A thread including its messages.

id
string
required

Thread id.

Example:

"thr_5aBcDeFgHiJkLmNoPq6r"

docId
string
required

Document the thread is anchored to.

Example:

"doc_S9tUvWxYzAbCdEfGh12i"

kind
enum<string>
required

Kind of discussion thread.

Available options:
comment,
suggestion
Example:

"comment"

anchorJson
string
required

Serialized Yjs relative positions ({from,to}) anchoring the thread.

Example:

"{\"from\":{\"type\":\"relative\",\"item\":10},\"to\":{\"type\":\"relative\",\"item\":24}}"

quotedText
string | null
required

Text that was selected when the thread was created.

Example:

"ship in Q2"

proposedText
string | null
required

Replacement text (legacy API-created replacement suggestions only). Accepting such a thread splices this text over the anchored range. Null for comments and suggesting-mode suggestions.

Example:

"ship in Q3"

sid
string | null
required

Suggesting-mode suggestion id (editor tracked changes only): identifies the suggestion_insert/suggestion_delete mark burst in the collaborative document. Accepting/rejecting such a thread resolves those marks. Null for comments and legacy replacement suggestions.

Example:

null

status
enum<string>
required

Current lifecycle status of the thread.

Available options:
open,
resolved,
accepted,
rejected
Example:

"open"

createdBy
string
required

User id of the thread creator.

Example:

"usr_V1StGXR8_Z5jdHi6BmyT"

createdByName
string | null
required

Display name of the thread creator — the creator's name or handle (agent creators carry the name of their API key). Null when the creator row no longer exists.

Example:

"Ada Lovelace"

createdByKind
enum<string> | null
required

Whether the thread creator is a person ('human') or an API-key agent identity ('agent'). Null when the creator row no longer exists.

Available options:
human,
agent,
null
Example:

"human"

createdAt
integer
required

When the thread was started (epoch milliseconds).

Example:

1752624000000

updatedAt
integer
required

When the thread last changed (epoch milliseconds).

Example:

1752624000000

resolvedBy
string | null
required

User id who resolved/accepted/rejected the thread, or null.

Example:

"usr_V1StGXR8_Z5jdHi6BmyT"

resolvedAt
integer | null
required

When the thread left the open state, or null.

Example:

1752624000000

messages
object[]
required

Messages, oldest first.

Example: