Comments

The conversations on a note — what somebody asked about a particular sentence, and everything said back. A thread is a conversation; a reply is one message in it.

Every call here carries Authorization: Bearer <key> and answers JSON. What is true of every call, and what every refusal means.

`GET` `/api/v1/w/:workspace_id/notes/:note_id/comments`

The conversations on a note, including the ones about its rows, cards and nodes.

needs: comment on the thing it touches
answers: threads, each with its about, its quote, and its replies.
refusals: unauthorized, not_found, too_many_requests

Parameters for GET /api/v1/w/:workspace_id/notes/:note_id/comments
Parameter	In	Type	Description
`page`	query	integer	Defaults to 1.
`per_page`	query	integer	Fifty by default, a hundred at most.
`include_resolved`	query	boolean	Closed ones as well. Open ones only by default.

A credential that may not see comments is told the conversation does not exist, rather than that it may not look — a refusal would itself say there is something there.

The server never says whether a quote still matches the note. Read the note with ?text=true and look for quote in that — it is the string a reader saw.

An example

curl -X GET https://goscribi.com/api/v1/w/10598/notes/13953/comments \
  -H "Authorization: Bearer $GO_SCRIBI_KEY"

Answers 200:

{
  "threads": [
    {
      "id": 397,
      "resolved": false,
      "about": {
        "type": "note",
        "id": 13953,
        "field": "body"
      },
      "quote": "The ferry terminal closes",
      "prefix": null,
      "suffix": null,
      "start_offset": null,
      "made_against": 0,
      "written_about": {
        "number": 0,
        "url": "https://goscribi.com/api/v1/w/10598/notes/13953/versions/0"
      },
      "started_by": "somebody@example.org",
      "started_at": "2026-09-16T01:10:29Z",
      "mine": false,
      "deletable": true,
      "replies": [
        {
          "id": 426,
          "body": "Is this still true?",
          "author": "somebody@example.org",
          "via": null,
          "edited": false,
          "created_at": "2026-09-16T01:10:29Z",
          "mine": false,
          "editable": false,
          "deletable": true
        }
      ]
    }
  ],
  "page": 1,
  "per_page": 50,
  "total": 1,
  "pages": 1
}

`POST` `/api/v1/w/:workspace_id/notes/:note_id/comments`

Start a conversation about a particular piece of text.

needs: comment on the thing it touches
answers: **201**, and the thread.
refusals: unauthorized, not_found, cannot_comment, workspace_locked, invalid

Parameters for POST /api/v1/w/:workspace_id/notes/:note_id/comments
Parameter	In	Type	Description
`quote` required	body	string	The words it is about, as a reader saw them.
`body` required	body	string	The first thing said. Markdown.
`prefix`	body	string
`suffix`	body	string
`start_offset`	body	integer
`end_offset`	body	integer
`about`	body	object	`{type, id}` for a checklist_item, board_card or map_node. Left out, it is about the note's body.

An example

curl -X POST https://goscribi.com/api/v1/w/11074/notes/11147/comments \
  -H "Authorization: Bearer $GO_SCRIBI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "quote": "The ferry terminal closes",
  "body": "Still true?"
}'

Answers 201:

{
  "id": 438,
  "resolved": false,
  "about": {
    "type": "note",
    "id": 11147,
    "field": "body"
  },
  "quote": "The ferry terminal closes",
  "prefix": null,
  "suffix": null,
  "start_offset": null,
  "made_against": 0,
  "written_about": {
    "number": 0,
    "url": "https://goscribi.com/api/v1/w/11074/notes/11147/versions/0"
  },
  "started_by": "somebody@example.org",
  "started_at": "2026-09-16T01:10:30Z",
  "mine": true,
  "deletable": true,
  "replies": [
    {
      "id": 448,
      "body": "Still true?",
      "author": "somebody@example.org",
      "via": null,
      "edited": false,
      "created_at": "2026-09-16T01:10:30Z",
      "mine": true,
      "editable": true,
      "deletable": true
    }
  ]
}

`PATCH` `PUT` `/api/v1/w/:workspace_id/notes/:note_id/comments/:id`

Resolve a conversation, or reopen it.

needs: comment on the thing it touches
answers: The thread.
refusals: unauthorized, not_found, cannot_comment

Parameters for PATCH /api/v1/w/:workspace_id/notes/:note_id/comments/:id
Parameter	In	Type	Description
`resolved` required	body	boolean

This is the only thing that resolves a thread. Replying never does, however much the reply sounds like an answer.

An example

curl -X PATCH https://goscribi.com/api/v1/w/9865/notes/14318/comments/359 \
  -H "Authorization: Bearer $GO_SCRIBI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "resolved": true
}'

Answers 200:

{
  "id": 359,
  "resolved": true,
  "about": {
    "type": "note",
    "id": 14318,
    "field": "body"
  },
  "quote": "The ferry terminal closes",
  "prefix": null,
  "suffix": null,
  "start_offset": null,
  "made_against": 0,
  "written_about": {
    "number": 0,
    "url": "https://goscribi.com/api/v1/w/9865/notes/14318/versions/0"
  },
  "started_by": "somebody@example.org",
  "started_at": "2026-09-16T01:10:30Z",
  "mine": false,
  "deletable": true,
  "replies": [
    {
      "id": 355,
      "body": "Is this still true?",
      "author": "somebody@example.org",
      "via": null,
      "edited": false,
      "created_at": "2026-09-16T01:10:30Z",
      "mine": false,
      "editable": false,
      "deletable": true
    }
  ]
}

`DELETE` `/api/v1/w/:workspace_id/notes/:note_id/comments/:id`

Remove a whole conversation.

needs: comment on the thing it touches
answers: **204**.
refusals: unauthorized, not_found, cannot_comment, not_yours

Yours only while it is still only yours — once somebody else has replied it takes an administrator. It is the one irreversible act here.

An example

curl -X DELETE https://goscribi.com/api/v1/w/10781/notes/11463/comments/455 \
  -H "Authorization: Bearer $GO_SCRIBI_KEY"

Answers 204:

null

`POST` `/api/v1/w/:workspace_id/notes/:note_id/comments/:comment_thread_id/replies`

Say something in a conversation.

needs: comment on the thing it touches
answers: **201**, and the reply.
refusals: unauthorized, not_found, cannot_comment, workspace_locked, invalid

Parameters for POST /api/v1/w/:workspace_id/notes/:note_id/comments/:comment_thread_id/replies
Parameter	In	Type	Description
`body` required	body	string	Markdown.

An example

curl -X POST https://goscribi.com/api/v1/w/11049/notes/12949/comments/459/replies \
  -H "Authorization: Bearer $GO_SCRIBI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "body": "Looks right."
}'

Answers 201:

{
  "id": 446,
  "body": "Looks right.",
  "author": "somebody@example.org",
  "via": null,
  "edited": false,
  "created_at": "2026-09-16T01:10:30Z",
  "mine": true,
  "editable": true,
  "deletable": true
}

`PATCH` `PUT` `/api/v1/w/:workspace_id/notes/:note_id/comments/:comment_thread_id/replies/:id`

Change something you said.

needs: comment on the thing it touches
answers: The reply, now marked as edited.
refusals: unauthorized, not_found, cannot_comment, not_yours

Parameters for PATCH /api/v1/w/:workspace_id/notes/:note_id/comments/:comment_thread_id/replies/:id
Parameter	In	Type	Description
`body` required	body	string

Your own words only. An administrator may delete anybody's comment and may never edit one — deleting is moderation, editing is authorship.

An example

curl -X PATCH https://goscribi.com/api/v1/w/11110/notes/10427/comments/415/replies/429 \
  -H "Authorization: Bearer $GO_SCRIBI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "body": "Still true? Checked the timetable."
}'

Answers 200:

{
  "id": 429,
  "body": "Still true? Checked the timetable.",
  "author": "somebody@example.org",
  "via": null,
  "edited": true,
  "created_at": "2026-09-16T01:10:29Z",
  "mine": true,
  "editable": true,
  "deletable": true
}

`DELETE` `/api/v1/w/:workspace_id/notes/:note_id/comments/:comment_thread_id/replies/:id`

Remove something said.

needs: comment on the thing it touches
answers: **204**.
refusals: unauthorized, not_found, cannot_comment, not_yours

An example

curl -X DELETE https://goscribi.com/api/v1/w/10827/notes/11857/comments/429/replies/435 \
  -H "Authorization: Bearer $GO_SCRIBI_KEY"

Answers 204:

null

The rest of the API

Notes A note is text, a checklist, a board or a map. These are the calls that make, read, change and bin one, whichever kind it is.
Checklist rows The rows of a checklist: their text, their own notes, what is ticked, and where each one sits in the tree.
Board columns and cards A board is cards in columns. Cards carry a description, an assignee, a due date and an estimate; columns carry a WIP limit and which one finishes.
Map nodes The nodes of a mind map: the same tree a checklist has, with a side and a colour.
Repeating tasks What comes back, and when. Rules are RFC 5545 `RRULE` strings — the ones every calendar exchanges — so a rule you already have can be handed over unchanged, and one you are given can be fed to a calendar.
Building a tree in one call Make a folder tree and the notes in it in one request, all or nothing. Name things with your own reference ids so a note can go in a folder the same call is about to make, try it without doing it, and send an idempotency key so a lost reply cannot build it twice.
Note properties Fields on a note itself — a review date, a status, where it came from — rather than words inside it. Every one is optional, and everything here is keyed by a property's KEY, which never changes when it is renamed.
History and undo Every write leaves a version. These read them, read what the note SAID at one of them, and take back a change.
Finding things Search, subjects, folders and templates: the calls a program makes before it knows which note it wants.
Claude, and other agents An MCP server on top of the same API, so a client that speaks MCP can work in a workspace without anybody copying a key. The tools are shaped like things people ask for rather than one per endpoint.
Workspaces and limits Which workspaces a credential reaches, what it may do in one, and what the plan allows.

Comments

GET /api/v1/w/:workspace_id/notes/:note_id/comments

POST /api/v1/w/:workspace_id/notes/:note_id/comments

PATCH PUT /api/v1/w/:workspace_id/notes/:note_id/comments/:id

DELETE /api/v1/w/:workspace_id/notes/:note_id/comments/:id

POST /api/v1/w/:workspace_id/notes/:note_id/comments/:comment_thread_id/replies

PATCH PUT /api/v1/w/:workspace_id/notes/:note_id/comments/:comment_thread_id/replies/:id

DELETE /api/v1/w/:workspace_id/notes/:note_id/comments/:comment_thread_id/replies/:id

`GET` `/api/v1/w/:workspace_id/notes/:note_id/comments`

`POST` `/api/v1/w/:workspace_id/notes/:note_id/comments`

`PATCH` `PUT` `/api/v1/w/:workspace_id/notes/:note_id/comments/:id`

`DELETE` `/api/v1/w/:workspace_id/notes/:note_id/comments/:id`

`POST` `/api/v1/w/:workspace_id/notes/:note_id/comments/:comment_thread_id/replies`

`PATCH` `PUT` `/api/v1/w/:workspace_id/notes/:note_id/comments/:comment_thread_id/replies/:id`

`DELETE` `/api/v1/w/:workspace_id/notes/:note_id/comments/:comment_thread_id/replies/:id`