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, 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
required

Serialized Yjs relative positions ({from,to}) for the selection.

Minimum string length: 1
Example:

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

body
string
required

First message of the thread.

Required string length: 1 - 10000
Example:

"Should this say Q3 instead of Q2?"

quotedText
string

Text selected when creating the thread.

Example:

"ship in Q2"

proposedText
string

Replacement text. Required when kind is suggestion.

Example:

"ship in Q3"

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 (suggestions only).

Example:

"ship in Q3"

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: