Post a new comment on a space or a specific page

Creates a new top-level comment on the space, optionally anchored to a specific page or a text selection within a page. Use this to leave feedback, start a review thread, or annotate content. To reply to an existing comment, use the comment replies endpoint.

Available in MCP

post

Authorizations

useroauth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

spaceIdstringRequired

A unique entity identifier

Pattern: ^[a-zA-Z0-9_-]+$

Body

application/json

nodestringOptional

The node to which the comment is posted, if any.

pagestringOptional

The page to which the comment is posted, if any.

bodyone ofRequired

The content of the comment.

or

or

object · EmptyOptional

Responses

200

The comment was posted.

application/json

and

anyOptional

or

post/spaces/{spaceId}/comments

HTTPcURLJavaScriptPython

POST /v1/spaces/{spaceId}/comments HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 191

{
  "node": "text",
  "page": "text",
  "body": {
    "markdown": "# Hello World\n\nThis is a markdown document linking to [another page](/pages/page_id).\n"
  },
  "tableCell": {
    "record": "text",
    "definition": "text"
  }
}

200

The comment was posted.

{
  "object": "comment",
  "id": "text",
  "postedBy": {
    "object": "user",
    "id": "text",
    "displayName": "text",
    "email": "text",
    "photoURL": "text",
    "urls": {
      "location": "https://example.com"
    }
  },
  "postedAt": "2026-07-22T00:29:25.923Z",
  "editedAt": "2026-07-22T00:29:25.923Z",
  "reactions": [
    {
      "emoji": "text",
      "count": 1,
      "users": [
        {
          "user": {
            "object": "user",
            "id": "text",
            "displayName": "text",
            "email": "text",
            "photoURL": "text",
            "urls": {
              "location": "https://example.com"
            }
          },
          "reactedAt": "2026-07-22T00:29:25.923Z"
        }
      ]
    }
  ],
  "replies": 1,
  "repliers": [
    {
      "updatedAt": "2026-07-22T00:29:25.923Z",
      "count": 1,
      "user": {
        "object": "user",
        "id": "text",
        "displayName": "text",
        "email": "text",
        "photoURL": "text",
        "urls": {
          "location": "https://example.com"
        }
      }
    }
  ],
  "body": {
    "markdown": "# Hello World\n\nThis is a markdown document linking to [another page](/pages/page_id).\n"
  },
  "target": {
    "node": {
      "id": "text"
    },
    "tableCell": {
      "record": "text",
      "definition": "text"
    },
    "changeRequest": "text",
    "review": "text",
    "page": {
      "id": "text"
    },
    "space": "text",
    "revision": "text"
  },
  "urls": {
    "location": "https://example.com"
  },
  "permissions": {
    "view": true,
    "edit": true,
    "reply": true,
    "delete": true
  },
  "status": "resolved",
  "resolvedAt": "2026-07-22T00:29:25.923Z",
  "resolvedBy": {
    "object": "user",
    "id": "text",
    "displayName": "text",
    "email": "text",
    "photoURL": "text",
    "urls": {
      "location": "https://example.com"
    }
  }
}