List comments

curl "https://api.bottari.ai/v1/comments?block_id=exampleRow01&page_size=50" \
  -H "Authorization: Bearer $BOTTARI_TOKEN" \
  -H "Bottari-Version: 2026-03-11"

{
  "object": "list",
  "results": [
    {
      "object": "comment",
      "id": "exampleCmt01",
      "parent": {
        "type": "page_id",
        "page_id": "exampleRow01"
      },
      "discussion_id": "exampleCmt01",
      "created_time": "2026-01-15T02:30:00.000Z",
      "last_edited_time": "2026-01-15T02:30:00.000Z",
      "created_by": {
        "object": "user",
        "id": "11111111-1111-4111-8111-111111111111"
      },
      "rich_text": [
        {
          "type": "text",
          "text": {
            "content": "Looks good.",
            "link": null
          },
          "annotations": {
            "bold": true,
            "italic": false,
            "strikethrough": false,
            "underline": false,
            "code": false,
            "color": "default"
          },
          "plain_text": "Looks good.",
          "href": null
        }
      ],
      "display_name": {
        "type": "user",
        "resolved_name": "Alex Kim"
      },
      "original_content_deleted": false,
      "has_pending_attachments": false
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "type": "comment",
  "comment": {},
  "request_id": "33333333-3333-4333-8333-333333333333"
}

{
  "object": "error",
  "status": 400,
  "code": "validation_error",
  "message": "query failed validation: query.block_id should be defined, instead was `undefined`.",
  "request_id": "33333333-3333-4333-8333-333333333333"
}

{
  "object": "error",
  "status": 403,
  "code": "restricted_resource",
  "message": "Insufficient permissions for this endpoint.",
  "request_id": "33333333-3333-4333-8333-333333333333"
}

GET

comments

curl "https://api.bottari.ai/v1/comments?block_id=exampleRow01&page_size=50" \
  -H "Authorization: Bearer $BOTTARI_TOKEN" \
  -H "Bottari-Version: 2026-03-11"

{
  "object": "list",
  "results": [
    {
      "object": "comment",
      "id": "exampleCmt01",
      "parent": {
        "type": "page_id",
        "page_id": "exampleRow01"
      },
      "discussion_id": "exampleCmt01",
      "created_time": "2026-01-15T02:30:00.000Z",
      "last_edited_time": "2026-01-15T02:30:00.000Z",
      "created_by": {
        "object": "user",
        "id": "11111111-1111-4111-8111-111111111111"
      },
      "rich_text": [
        {
          "type": "text",
          "text": {
            "content": "Looks good.",
            "link": null
          },
          "annotations": {
            "bold": true,
            "italic": false,
            "strikethrough": false,
            "underline": false,
            "code": false,
            "color": "default"
          },
          "plain_text": "Looks good.",
          "href": null
        }
      ],
      "display_name": {
        "type": "user",
        "resolved_name": "Alex Kim"
      },
      "original_content_deleted": false,
      "has_pending_attachments": false
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "type": "comment",
  "comment": {},
  "request_id": "33333333-3333-4333-8333-333333333333"
}

{
  "object": "error",
  "status": 400,
  "code": "validation_error",
  "message": "query failed validation: query.block_id should be defined, instead was `undefined`.",
  "request_id": "33333333-3333-4333-8333-333333333333"
}

{
  "object": "error",
  "status": 403,
  "code": "restricted_resource",
  "message": "Insufficient permissions for this endpoint.",
  "request_id": "33333333-3333-4333-8333-333333333333"
}

Reads comments and replies in creation order. Requires Read comments. Writing comments isn’t available.

string

required

Bearer <token>. See Tokens.

string

Optional. Only 2026-03-11 is accepted. Without it, the current version is used. A different value returns 400.

string

required

A page ID or block ID. The format isn’t checked, and an unknown ID returns 404.

number

default:"100"

1 to 100.

string

next_cursor from the previous response. It’s the ID of the next comment.

What’s returned

`block_id`	Result
Page ID	Comments on the page and their replies. Comments whose block is gone also move here. Comments on live blocks don’t appear.
Block ID	Comments on that block and their replies. A comment on text counts as a comment on the block holding that text.

Resolved threads are left out of the list, including replies. Retrieve a comment can still read them.
Deleted comments are left out of the list. Deleting a thread also deletes its replies.
A comment whose block is gone, read by that block ID, has rich_text: []. The page ID or Retrieve a comment returns the text.
discussion_id differs per thread for page comments. A reply’s discussion_id matches the first comment of its thread.
Comments on a trashed row have rich_text: [] and original_content_deleted: true. Restoring the row brings the text back.

Comment object

For a comment on text in a subpage card, parent has the form {document id}.{block}. Reading a block with this ID returns 404, but you can use it as block_id here.

string

The comment ID.

object

{ "type": "page_id", "page_id": "..." } or { "type": "block_id", "block_id": "..." }. A reply matches the first comment of its thread.

string

The thread ID, which matches the first comment’s ID.

string

Creation time, in UTC, truncated to the minute.

string

Last edit time. If it was never edited, this is the creation time.

object

{ "object": "user", "id": "..." }.

object[]

Rich text items split every 2,000 characters, with a newline item between paragraphs. A comment with only attachments has [].

object

{ "type": "user", "resolved_name": "Name" } for a person, { "type": "integration", "resolved_name": "보따리" } for a comment Bottari wrote.

boolean

true if the original text or block is gone, or the row is in the trash.

boolean

Always false.

Errors

Status	`code`	Cause
400	`validation_error`	`block_id` is missing, `page_size` is wrong, or `start_cursor` isn’t a comment in this document.
403	`restricted_resource`	Read comments is off.
404	`object_not_found`	The page or block doesn’t exist, or the integration can’t read it.

See Common rules for shared errors.

curl "https://api.bottari.ai/v1/comments?block_id=exampleRow01&page_size=50" \
  -H "Authorization: Bearer $BOTTARI_TOKEN" \
  -H "Bottari-Version: 2026-03-11"

{
  "object": "list",
  "results": [
    {
      "object": "comment",
      "id": "exampleCmt01",
      "parent": {
        "type": "page_id",
        "page_id": "exampleRow01"
      },
      "discussion_id": "exampleCmt01",
      "created_time": "2026-01-15T02:30:00.000Z",
      "last_edited_time": "2026-01-15T02:30:00.000Z",
      "created_by": {
        "object": "user",
        "id": "11111111-1111-4111-8111-111111111111"
      },
      "rich_text": [
        {
          "type": "text",
          "text": {
            "content": "Looks good.",
            "link": null
          },
          "annotations": {
            "bold": true,
            "italic": false,
            "strikethrough": false,
            "underline": false,
            "code": false,
            "color": "default"
          },
          "plain_text": "Looks good.",
          "href": null
        }
      ],
      "display_name": {
        "type": "user",
        "resolved_name": "Alex Kim"
      },
      "original_content_deleted": false,
      "has_pending_attachments": false
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "type": "comment",
  "comment": {},
  "request_id": "33333333-3333-4333-8333-333333333333"
}

{
  "object": "error",
  "status": 400,
  "code": "validation_error",
  "message": "query failed validation: query.block_id should be defined, instead was `undefined`.",
  "request_id": "33333333-3333-4333-8333-333333333333"
}

{
  "object": "error",
  "status": 403,
  "code": "restricted_resource",
  "message": "Insufficient permissions for this endpoint.",
  "request_id": "33333333-3333-4333-8333-333333333333"
}

Common

Users

Search

Databases and data sources

Pages

Blocks

Comments

What’s returned

Comment object

Errors

​What’s returned

​Comment object

​Errors

What’s returned

Comment object

Errors