API reference
12 endpoints, served at https://orbitwrite.com/api/v1. Each one lists the credentials it accepts, its parameters and every response it can give.
/api/v1/commentsPOST/api/v1/commentsPUT/api/v1/comments/post-mutePOST/api/v1/comments/read-allPOST/api/v1/comments/{id}/repliesPATCH/api/v1/comments/{id}DEL/api/v1/comments/{id}PUT/api/v1/comments/{id}/resolvedPUT/api/v1/comments/{id}/reactionPOST/api/v1/comments/{id}/decisionPUT/api/v1/comments/{id}/mutePUT/api/v1/comments/{id}/readWith groupId: that group's whole comment list, oldest first, plus the caller's mute and read state for it. A brand-new unsaved draft (no group row yet) returns an empty result. Without it: every comment in the workspace (organizationId), newest first and cursor-paged, filterable by resolved, kind, suggestionStatus and suggestionType; the mute and read state then cover the threads on the page, and postMuted is always false. The filters and cursor belong to the workspace listing and are refused alongside groupId.
A signed-in session only. The Orbitwrite app calls this; an API key is refused.
groupIdstringAt least 1 character.
organizationIdstringThe workspace to list when groupId is omitted. Defaults to the session's active workspace.
At least 1 character.
limitintegerWorkspace listing page size (default 50).
Between 1 and 100.
cursorstringOpaque cursor from a previous response's nextCursor. Omit for the first page.
resolvedstringOnly resolved rows, or only open ones. A decided suggestion counts as resolved. Omit for both.
"true""false"kindstring"comment""suggestion"suggestionStatusstring | string[]A suggestion's decision state. Repeat for OR.
suggestionTypestring | string[]Which edit a suggestion tracks. Repeat for OR (e.g. ?suggestionType=insert&suggestionType=replace).
200CommentsListComments, with the caller's mute and read state for the group (or the page's threads).
okbooleanRequiredcommentsComment[]RequiredidstringRequiredgroupIdstringRequiredThe composer group (post) the comment hangs off.
parentIdstring | nullRequiredaccountIdstring | nullRequiredthreadPositionnumber | nullRequiredquotestring | nullRequiredbodystringRequiredattachmentsCommentAttachment[]RequiredreactionsCommentReaction[]RequiredemojistringRequiredcountnumberRequiredreactedByMebooleanRequiredresolvedbooleanRequiredcreatedAtnumberRequiredEpoch ms.
kindstringRequired"comment" (default) or "suggestion" — a tracked insert/delete made in suggestion mode.
"comment""suggestion"suggestionTypestring | nullRequired"insert""delete""replace"nullsuggestionStatusstring | nullRequired"pending""accepted""rejected"nullpostMutedbooleanRequiredmutedThreadIdsstring[]RequiredreadStateobjectRequiredthreadId → lastReadAt (epoch ms) for the requesting user.
nextCursorstring | nullRequiredWorkspace listing only: pass back as cursor for the next page; null on the last page. Always null for one group, which is returned whole.
curl -X GET "https://orbitwrite.com/api/v1/comments" \
-H "Authorization: Bearer $ORBITWRITE_API_KEY"{
"ok": true,
"comments": [
{
"id": "string",
"groupId": "string",
"parentId": "string",
"accountId": "string",
"threadPosition": 0,
"quote": "string",
"body": "string",
"attachments": [
{
"url": "string",
"mimeType": "string"
}
],
"mentions": [
{
"userId": "string",
"name": "string"
}
],
"reactions": [
{
"emoji": "string",
"count": 0,
"reactedByMe": true
}
],
"resolved": true,
"createdAt": 0,
"author": {
"id": "string",
"name": "string",
"avatarUrl": "string"
},
"kind": "comment",
"suggestionType": "insert",
"suggestionStatus": "pending"
}
],
"postMuted": true,
"mutedThreadIds": [
"string"
],
"readState": {},
"nextCursor": "string"
}Adds a top-level review comment (or a tracked suggestion) to a composer group. Any member of the group's organization may comment; a suggestion also needs a plan that includes suggested edits (Pro and up). Retrying with the same id is idempotent.
A signed-in session only. The Orbitwrite app calls this; an API key is refused.
groupIdstringRequiredThe composer group the comment belongs to.
At least 1 character.
idstringFormat uuid.
accountIdstring | nullthreadPositionnumber | nullquotestring | nullbodystringattachmentsany[]mentionsany[]kindstring"comment""suggestion"suggestionTypestring"insert""delete""replace"200CreatedCommentThe comment was created; id is the persisted id.
curl -X POST "https://orbitwrite.com/api/v1/comments" \
-H "Authorization: Bearer $ORBITWRITE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"groupId": "string"
}'{
"ok": true,
"id": "string"
}Sets the caller's post-level subscription: muted unsubscribes them from all comment activity on the group. Per-user — nobody else's notifications change.
A signed-in session only. The Orbitwrite app calls this; an API key is refused.
groupIdstringRequiredThe composer group the comment belongs to.
At least 1 character.
mutedbooleanRequired200CommentActionResultThe operation was applied
okbooleanRequiredcurl -X PUT "https://orbitwrite.com/api/v1/comments/post-mute" \
-H "Authorization: Bearer $ORBITWRITE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"groupId": "string",
"muted": true
}'{
"ok": true
}Stamps the caller's read marker for every thread in the group at now.
A signed-in session only. The Orbitwrite app calls this; an API key is refused.
groupIdstringRequiredThe composer group the comment belongs to.
At least 1 character.
200CommentActionResultThe operation was applied
okbooleanRequiredcurl -X POST "https://orbitwrite.com/api/v1/comments/read-all" \
-H "Authorization: Bearer $ORBITWRITE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"groupId": "string"
}'{
"ok": true
}Adds a reply under a top-level comment. Replies can't nest further. Retrying with the same id is idempotent.
A signed-in session only. The Orbitwrite app calls this; an API key is refused.
200CreatedCommentThe reply was created; id is the persisted id.
400ErrorInvalid request
401ErrorNot signed in
403ErrorNot a member of the organization
404ErrorGroup or parent comment not found
curl -X POST "https://orbitwrite.com/api/v1/comments/{id}/replies" \
-H "Authorization: Bearer $ORBITWRITE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"groupId": "string"
}'{
"ok": true,
"id": "string"
}Author-only: updates a comment's (or reply's) body, attachments and mentions. Suggestion quote-sync edits also carry quote.
A signed-in session only. The Orbitwrite app calls this; an API key is refused.
idstringRequiredAt least 1 character.
groupIdstringRequiredThe composer group the comment belongs to.
At least 1 character.
bodystringattachmentsany[]mentionsany[]quotestring | null200CommentActionResultThe operation was applied
okbooleanRequiredcurl -X PATCH "https://orbitwrite.com/api/v1/comments/{id}" \
-H "Authorization: Bearer $ORBITWRITE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"groupId": "string"
}'{
"ok": true
}Removes a comment or reply. Authors delete their own; a caller with comment:manageAny (manager and up) may also remove someone else's. Deleting a top-level comment removes its whole thread.
A signed-in session only. The Orbitwrite app calls this; an API key is refused.
idstringRequiredAt least 1 character.
groupIdstringRequiredAt least 1 character.
200CommentActionResultThe operation was applied
okbooleanRequiredcurl -X DELETE "https://orbitwrite.com/api/v1/comments/{id}?groupId=groupId" \
-H "Authorization: Bearer $ORBITWRITE_API_KEY"{
"ok": true
}Sets the thread's resolved state. Any member of the group's organization may resolve — not just the author.
A signed-in session only. The Orbitwrite app calls this; an API key is refused.
idstringRequiredAt least 1 character.
groupIdstringRequiredThe composer group the comment belongs to.
At least 1 character.
resolvedbooleanRequired200CommentActionResultThe operation was applied
okbooleanRequiredcurl -X PUT "https://orbitwrite.com/api/v1/comments/{id}/resolved" \
-H "Authorization: Bearer $ORBITWRITE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"groupId": "string",
"resolved": true
}'{
"ok": true
}Sets the caller's reaction with one emoji on a comment or reply.
A signed-in session only. The Orbitwrite app calls this; an API key is refused.
idstringRequiredAt least 1 character.
groupIdstringRequiredThe composer group the comment belongs to.
At least 1 character.
emojistringRequiredAt least 1 character.
reactedbooleanRequiredDesired end state: true adds the caller's reaction, false removes it. Idempotent either way.
200CommentActionResultThe operation was applied
okbooleanRequiredcurl -X PUT "https://orbitwrite.com/api/v1/comments/{id}/reaction" \
-H "Authorization: Bearer $ORBITWRITE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"groupId": "string",
"emoji": "string",
"reacted": true
}'{
"ok": true
}Decides a tracked suggestion, marking it resolved. The decision is terminal: retrying the same decision is idempotent, flipping it is a conflict.
A signed-in session only. The Orbitwrite app calls this; an API key is refused.
idstringRequiredAt least 1 character.
groupIdstringRequiredThe composer group the comment belongs to.
At least 1 character.
decisionstringRequired"accepted""rejected"200CommentActionResultThe operation was applied
okbooleanRequiredcurl -X POST "https://orbitwrite.com/api/v1/comments/{id}/decision" \
-H "Authorization: Bearer $ORBITWRITE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"groupId": "string",
"decision": "accepted"
}'{
"ok": true
}Sets the caller's mute state for one thread (a top-level comment): muted threads stop notifying them. Per-user — nobody else's notifications change.
A signed-in session only. The Orbitwrite app calls this; an API key is refused.
idstringRequiredAt least 1 character.
groupIdstringRequiredThe composer group the comment belongs to.
At least 1 character.
mutedbooleanRequired200CommentActionResultThe operation was applied
okbooleanRequiredcurl -X PUT "https://orbitwrite.com/api/v1/comments/{id}/mute" \
-H "Authorization: Bearer $ORBITWRITE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"groupId": "string",
"muted": true
}'{
"ok": true
}Stamps the caller's read marker for one thread (a top-level comment) at now.
A signed-in session only. The Orbitwrite app calls this; an API key is refused.
idstringRequiredAt least 1 character.
groupIdstringRequiredThe composer group the comment belongs to.
At least 1 character.
200CommentActionResultThe operation was applied
okbooleanRequiredcurl -X PUT "https://orbitwrite.com/api/v1/comments/{id}/read" \
-H "Authorization: Bearer $ORBITWRITE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"groupId": "string"
}'{
"ok": true
}