Create a comment thread on a document
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.
AuthorizationBearer <token>API key, e.g. Authorization: Bearer sajn_svc_.... Not scope-limited: acts with its owner's workspace role.
id*stringThe document ID.
Sajn-Version?stringAPI 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.
"2026-09""2026-10"Sajn-Workspace?stringID 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?stringMakes 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.
length <= 255Body
application/json- body
body*stringInitial message body for the new thread
1 <= lengthexcerpt?|Optional excerpt of the document content the thread refers to
mentions?array<string>User IDs mentioned in the message
visibility?stringSHARED makes the thread visible to every party on the document; INTERNAL (the default) keeps it to the workspace
"INTERNAL""SHARED"contentId?stringThe content block the thread is on. With excerpt, sajn highlights the excerpt in that block. Without contentId, the thread is on the whole document.
1 <= lengthprefix?stringUp to 200 characters of the text right before the excerpt. Picks the occurrence when the excerpt appears more than once in the block.
length <= 200suffix?stringUp to 200 characters of the text right after the excerpt. Picks the occurrence when the excerpt appears more than once in the block.
length <= 200externalId?stringYour 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.
1 <= length <= 200200
application/json- response
id*stringThe comment thread ID.
documentId*|The document ID.
status*stringWhether the thread is open or resolved.
"OPEN""RESOLVED"visibility*stringIf SHARED, every party on the document sees the thread. If INTERNAL, only the workspace does.
"INTERNAL""SHARED"excerpt*|The document text the thread refers to.
createdAt*stringWhen the comment thread was created.
date-timeupdatedAt*stringWhen the comment thread was last updated.
date-timeresolvedAt*|When the thread was resolved. Null while it's open.
date-timecreatedBy*|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.
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"}'{ "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?