Skip to main content
POST
Create a comment thread on a document

Authorizations

Authorization
string
header
required

API key, e.g. Authorization: Bearer sajn_svc_.... Not scope-limited: acts with its owner's workspace role.

Scopes

documents:write

Create documents and edit the documents the user created.

Headers

Sajn-Version
enum<string>

API version for this request. Without it, the request uses the organization's default version; an organization without a default is pinned to the latest version by its first request.

Available options:
2026-09,
2026-10
Sajn-Workspace
string

ID of the workspace this request acts in, from GET /api/v1/workspaces. Without it, an API key acts in its default workspace. The token's user must be a member of the workspace; an OAuth token only accepts the workspace it was granted for. A workspace that doesn't exist or can't be reached returns 403 WORKSPACE_ACCESS_DENIED.

Idempotency-Key
string

Makes retries safe. A retry with the same key and the same request replays the stored response for 24 hours (header Idempotent-Replayed: true); the same key with a different request returns 400.

Maximum string length: 255

Path Parameters

id
string
required

The document ID.

Body

application/json

Body

body
string
required

Initial message body for the new thread

Minimum string length: 1
excerpt
string | null

Optional excerpt of the document content the thread refers to

mentions
string[]

User IDs mentioned in the message

visibility
enum<string>

SHARED makes the thread visible to every party on the document; INTERNAL (the default) keeps it to the workspace

Available options:
INTERNAL,
SHARED
contentId
string

The content block the thread is on. With excerpt, sajn highlights the excerpt in that block. Without contentId, the thread is on the whole document.

Minimum string length: 1
prefix
string

Up to 200 characters of the text right before the excerpt. Picks the occurrence when the excerpt appears more than once in the block.

Maximum string length: 200
suffix
string

Up to 200 characters of the text right after the excerpt. Picks the occurrence when the excerpt appears more than once in the block.

Maximum string length: 200
externalId
string

Your own ID for the thread, such as the ID of a comment you import. A second request with the same externalId on the document returns the thread the first one created.

Required string length: 1 - 200

Response

200

id
string
required

The comment thread ID.

documentId
string | null
required

The document ID.

status
enum<string>
required

Whether the thread is open or resolved.

Available options:
OPEN,
RESOLVED
visibility
enum<string>
required

If SHARED, every party on the document sees the thread. If INTERNAL, only the workspace does.

Available options:
INTERNAL,
SHARED
excerpt
string | null
required

The document text the thread refers to.

createdAt
string<date-time>
required

When the comment thread was created.

updatedAt
string<date-time>
required

When the comment thread was last updated.

resolvedAt
string<date-time> | null
required

When the thread was resolved. Null while it's open.

createdBy
object | null
required

Who wrote it. Null when the author no longer exists.

resolvedBy
object | null
required

Who wrote it. Null when the author no longer exists.

messages
object[]
required

The thread's messages, oldest first.