Skip to Content
Document comments

Create a comment thread on a document

POST
/api/v1/documents/{id}/comments

Start a new comment thread on a document with an initial message. Mention users by passing their user IDs in mentions.

To place the thread on a passage, send the passage as excerpt and the block it's in as contentId. If the excerpt appears more than once in the block, prefix and suffix pick the occurrence. To import comments from another tool without duplicates, send each with its own externalId. A request with an externalId the document already has returns that thread and creates nothing.

Authorization

headerAuthorizationBearer <token>

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

Path Parameters

id*string

The document ID.

Header Parameters

Sajn-Version?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.

Value in"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.

Lengthlength <= 255

Request Body

Body

application/json
  1. body
body*string

Initial message body for the new thread

Length1 <= length
excerpt?|

Optional excerpt of the document content the thread refers to

mentions?array<string>

User IDs mentioned in the message

visibility?string

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

Value in"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.

Length1 <= length
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.

Lengthlength <= 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.

Lengthlength <= 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.

Length1 <= length <= 200

Response Body

200

application/json
  1. response
id*string

The comment thread ID.

documentId*|

The document ID.

status*string

Whether the thread is open or resolved.

Value in"OPEN""RESOLVED"
visibility*string

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

Value in"INTERNAL""SHARED"
excerpt*|

The document text the thread refers to.

createdAt*string

When the comment thread was created.

Formatdate-time
updatedAt*string

When the comment thread was last updated.

Formatdate-time
resolvedAt*|

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

Formatdate-time
createdBy*|

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

resolvedBy*|

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

messages*array<>

The thread's messages, oldest first.

Example Request
curl -X POST 'https://app.sajn.se/api/v1/documents/cm4k2x9p10003abcd1234efgh/comments' \  -H 'Content-Type: application/json' \  -d '{  "body": "Kan vi ändra startdatum till den 1 december?",  "excerpt": "Anställningen börjar den 1 november 2026",  "mentions": [    "cm4k2x9p10002abcd1234efgh"  ],  "visibility": "INTERNAL",  "contentId": "cm4k2x9p10018abcd1234efgh",  "prefix": "Anställningsavtal – Kai Lindqvist",  "suffix": "Anställningsavtal – Kai Lindqvist",  "externalId": "HR-2026-0142"}'
Example Response
{  "id": "cm4k2x9p10018abcd1234efgh",  "documentId": "cm4k2x9p10003abcd1234efgh",  "status": "OPEN",  "visibility": "INTERNAL",  "excerpt": "Anställningen börjar den 1 november 2026",  "createdAt": "2026-09-28T09:12:00.000Z",  "updatedAt": "2026-09-28T09:15:00.000Z",  "resolvedAt": null,  "createdBy": {    "id": "cm4k2x9p10002abcd1234efgh",    "name": "Alex Berg",    "email": "alex@example.com"  },  "resolvedBy": null,  "messages": [    {      "id": "cm4k2x9p10019abcd1234efgh",      "threadId": "cm4k2x9p10018abcd1234efgh",      "parentId": "cm4k2x9p10019abcd1234efgh",      "body": "Kan vi ändra startdatum till den 1 december?",      "mentions": [        "cm4k2x9p10002abcd1234efgh"      ],      "createdAt": "2026-09-28T09:12:00.000Z",      "editedAt": null,      "deletedAt": null,      "author": {        "type": "USER",        "id": "cm4k2x9p10002abcd1234efgh",        "name": "Alex Berg",        "email": "alex@example.com"      }    }  ]}

Was this page helpful?