### Install Notion Ruby Client Gem

Source: https://github.com/phacks/notion-ruby-client/blob/main/README.md

Instructions to add the notion-ruby-client gem to your project's Gemfile and install it using bundler.

```ruby
gem 'notion-ruby-client'

# Run bundle install
```

--------------------------------

### Install Project Dependencies - Ruby

Source: https://github.com/phacks/notion-ruby-client/blob/main/CONTRIBUTING.md

Installs the necessary Ruby gems for the project using Bundler. This command should be run after cloning the repository and before running tests or other project commands.

```bash
bundle install
```

--------------------------------

### Run Project Specs Locally - Ruby

Source: https://github.com/phacks/notion-ruby-client/blob/main/CONTRIBUTING.md

This command executes the project's specifications using Bundler and Rake. Ensure you have cloned the repository and installed dependencies using 'bundle install' before running.

```bash
bundle exec rake
```

--------------------------------

### Start Interactive Ruby Console - Ruby

Source: https://github.com/phacks/notion-ruby-client/blob/main/CONTRIBUTING.md

Launches an interactive Ruby console session with all project gem files loaded. This is useful for experimenting with the client and testing functionality directly.

```bash
bin/console
```

--------------------------------

### Query Notion Database with Ruby

Source: https://github.com/phacks/notion-ruby-client/blob/main/README.md

Retrieves paginated lists of page objects from a Notion database, with options for filtering and sorting. It supports basic retrieval, pagination using a start cursor, and advanced filtering based on property values. Dependencies include the notion-ruby-client.

```ruby
client.database_query(database_id: 'e383bcee-e0d8-4564-9c63-900d307abdb0')  # retrieves the first page

client.database_query(database_id: 'e383bcee-e0d8-4564-9c63-900d307abdb0', start_cursor: 'fe2cc560-036c-44cd-90e8-294d5a74cebc')

client.database_query(database_id: 'e383bcee-e0d8-4564-9c63-900d307abdb0') do |page|
  # paginate through all pages
end

# Filter and sort the database
sorts = [
  {
    'timestamp': 'created_time',
    'direction': 'ascending'
  }
]
filter = {
  'or': [
    {
      'property': 'In stock',
      'checkbox': {
        'equals': true
      }
    },
    {
      'property': 'Cost of next trip',
      'number': {
        'greater_than_or_equal_to': 2
      }
    }
  ]
}
client.database_query(database_id: 'e383bcee-e0d8-4564-9c63-900d307abdb0', sorts: sorts, filter: filter)
```

--------------------------------

### GET /blocks/{block_id}/children

Source: https://github.com/phacks/notion-ruby-client/blob/main/README.md

Retrieves a paginated list of child block objects for a given block ID. Use this endpoint recursively to get all descendants.

```APIDOC
## Retrieve block children

### Description
Returns a paginated array of child block objects contained in the block using the ID specified. In order to receive a complete representation of a block, you may need to recursively retrieve the block children of child blocks.

### Method
GET

### Endpoint
`/v1/blocks/{block_id}/children`

### Parameters
#### Path Parameters
- **block_id** (string) - Required - The ID of the block whose children to retrieve.

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of items to return.
- **start_cursor** (string) - Optional - The cursor to start retrieving results from.

### Request Example
```ruby
# Retrieve first page of children
client.block_children(block_id: 'b55c9c91-384d-452b-81db-d1ef79372b75')

# Retrieve next page of children
client.block_children(block_id: 'b55c9c91-384d-452b-81db-d1ef79372b75', start_cursor: 'fe2cc560-036c-44cd-90e8-294d5a74cebc')

# Paginate through all children
client.block_children(block_id: 'b55c9c91-384d-452b-81db-d1ef79372b75') do |page|
  # Process each page of children
end
```

### Response
#### Success Response (200)
- **object** (string) - "list"
- **results** (array) - An array of block objects.
- **next_cursor** (string or null) - The cursor to use to retrieve the next page of results.
- **has_more** (boolean) - Whether there are more pages of results.

#### Response Example
```json
{
  "object": "list",
  "results": [
    {
      "object": "block",
      "id": "f8f0f9a4-7873-4730-9602-39d2819021f1",
      "parent": {
        "type": "block_id",
        "block_id": "b55c9c91-384d-452b-81db-d1ef79372b75"
      },
      "created_time": "2021-05-22T19:00:00.000Z",
      "last_edited_time": "2021-05-22T19:00:00.000Z",
      "has_children": false,
      "type": "paragraph",
      "paragraph": {
        "rich_text": [
          {
            "type": "text",
            "text": {
              "content": "Child paragraph.",
              "link": null
            }
          }
        ],
        "color": "default"
      }
    }
  ],
  "next_cursor": null,
  "has_more": false
}
```
```

--------------------------------

### GET /blocks/{block_id}

Source: https://github.com/phacks/notion-ruby-client/blob/main/README.md

Retrieves a specific block object using its unique ID. If the block has children, you can use the Retrieve block children endpoint to fetch them.

```APIDOC
## Retrieve a block

### Description
Retrieves a Block object using the ID specified. If a block contains the key `has_children: true`, use the [Retrieve block children](#retrieve-block-children) endpoint to get the list of children.

### Method
GET

### Endpoint
`/v1/blocks/{block_id}`

### Parameters
#### Path Parameters
- **block_id** (string) - Required - The ID of the block to retrieve.

### Request Example
```ruby
client.block(block_id: '9bc30ad4-9373-46a5-84ab-0a7845ee52e6')
```

### Response
#### Success Response (200)
- **Block object** (object) - The retrieved block object.

#### Response Example
```json
{
  "object": "block",
  "id": "9bc30ad4-9373-46a5-84ab-0a7845ee52e6",
  "parent": {
    "type": "page_id",
    "page_id": "7b572834-133c-4977-857a-746734136a3e"
  },
  "created_time": "2021-03-16T20:26:00.000Z",
  "last_edited_time": "2021-03-16T20:26:00.000Z",
  "has_children": false,
  "type": "paragraph",
  "paragraph": {
    "rich_text": [
      {
        "type": "text",
        "text": {
          "content": "This is a paragraph.",
          "link": null
        }
      }
    ],
    "color": "default"
  }
}
```
```

--------------------------------

### Instantiate Notion API Client

Source: https://github.com/phacks/notion-ruby-client/blob/main/README.md

Shows how to create a new instance of the Notion API client. It also demonstrates how to specify the API token and a logger directly during instantiation.

```ruby
client = Notion::Client.new

# With specific token and logger
client = Notion::Client.new(token: '<secret Notion API token>', logger: my_logger)
```

--------------------------------

### Initialize Notion Client - Ruby

Source: https://github.com/phacks/notion-ruby-client/blob/main/CONTRIBUTING.md

Demonstrates how to initialize a new Notion client instance within an interactive Ruby console. Requires a valid Notion API token.

```ruby
client = Notion::Client.new(token: <Your Notion API token>)
```

--------------------------------

### Create Notion Database with Ruby

Source: https://github.com/phacks/notion-ruby-client/blob/main/README.md

Creates a new Notion database as a subpage of a specified parent page. It defines the database title and its properties schema, including various types like title, rich text, checkbox, and select options. Requires the notion-ruby-client.

```ruby
title = [
  {
    'type': 'text',
    'text': {
      'content': 'Grocery List',
      'link': nil
    }
  }
]
properties = {
  'Name': {
    'title': {}
  },
  'Description': {
    'rich_text': {}
  },
  'In stock': {
    'checkbox': {}
  },
  'Food group': {
    'select': {
      'options': [
        {
          'name': '🥦Vegetable',
          'color': 'green'
        },
        {
          'name': '🍎Fruit',
          'color': 'red'
        },
        {
          'name': '💪Protein',
          'color': 'yellow'
        }
      ]
    }
  }
}
client.create_database(
  parent: { page_id: '98ad959b-2b6a-4774-80ee-00246fb0ea9b' },
  title: title,
  properties: properties
)
```

--------------------------------

### Configure Notion API Token

Source: https://github.com/phacks/notion-ruby-client/blob/main/README.md

Demonstrates how to configure the Notion API token using an environment variable for authentication with the Notion API. This is typically placed in the application's configuration file.

```ruby
Notion.configure do |config|
  config.token = ENV['NOTION_API_TOKEN']
end
```

--------------------------------

### Search Pages and Databases with Notion Ruby Client

Source: https://github.com/phacks/notion-ruby-client/blob/main/README.md

Searches for pages and databases shared with the integration. Supports general search, filtering by query, object type, sorting, and pagination.

```ruby
client.search # search through every available page and database
```

```ruby
client.search(query: 'Specific query') # limits which pages are returned by comparing the query to the page title
```

```ruby
client.search(filter: { property: 'object', value: 'page' }) # only returns pages
```

```ruby
client.search(sort: { direction: 'ascending', timestamp: 'last_edited_time' }) # sorts the results based on the provided criteria.
```

```ruby
client.search(start_cursor: 'fe2cc560-036c-44cd-90e8-294d5a74cebc')
```

```ruby
client.search do |page|
  # paginate through all search pages
end
```

--------------------------------

### List All Users with Notion Ruby Client

Source: https://github.com/phacks/notion-ruby-client/blob/main/README.md

Retrieves a paginated list of users in a Notion workspace. Supports fetching the first page, specific pages using a cursor, or iterating through all users.

```ruby
client.users_list # retrieves the first page
```

```ruby
client.users_list(start_cursor: 'fe2cc560-036c-44cd-90e8-294d5a74cebc')
```

```ruby
client.users_list do |page|
  # paginate through all users
end
```

--------------------------------

### Pages API

Source: https://github.com/phacks/notion-ruby-client/blob/main/README.md

Endpoints for interacting with Notion pages, including retrieving, creating, updating, and retrieving page property items.

```APIDOC
## GET /v1/pages/{page_id}

### Description
Retrieves a page.

### Method
GET

### Endpoint
/v1/pages/{page_id}

### Parameters
#### Path Parameters
- **page_id** (string) - Required - The ID of the page to retrieve.

### Response
#### Success Response (200)
- **object** (string) - Type of object, "page".
- **id** (string) - The ID of the page.
- **properties** (object) - The properties of the page.

#### Response Example
```json
{
  "object": "page",
  "id": "<page-id>",
  "title": [
    {
      "type": "text",
      "text": {
        "content": "Sample Page Title"
      }
    }
  ],
  "properties": {
    "Name": {
      "title": [
        {
          "type": "text",
          "text": {
            "content": "Sample Page Title"
          }
        }
      ]
    }
  },
  "created_time": "2021-05-22T12:00:00.000Z",
  "last_edited_time": "2021-05-22T12:00:00.000Z",
  "created_by": {
    "object": "user",
    "id": "<user-id>"
  },
  "last_edited_by": {
    "object": "user",
    "id": "<user-id>"
  },
  "icon": null,
  "cover": null,
  "url": "https://www.notion.so/<user-id>/<page-id>"
}
```
```

```APIDOC
## POST /v1/pages

### Description
Creates a new page.

### Method
POST

### Endpoint
/v1/pages

### Parameters
#### Request Body
- **parent** (object) - Required - The parent of the page (e.g., a database or a page).
- **properties** (object) - Required - The properties of the page.

### Request Example
```json
{
  "parent": {
    "database_id": "<database-id>"
  },
  "properties": {
    "Name": {
      "title": [
        {
          "type": "text",
          "text": {
            "content": "New Page Title"
          }
        }
      ]
    },
    "Status": {
      "select": {
        "name": "To Do"
      }
    }
  }
}
```

### Response
#### Success Response (200)
- **object** (string) - Type of object, "page".
- **id** (string) - The ID of the newly created page.
- **properties** (object) - The properties of the page.

#### Response Example
```json
{
  "object": "page",
  "id": "<new-page-id>",
  "title": [
    {
      "type": "text",
      "text": {
        "content": "New Page Title"
      }
    }
  ],
  "properties": {
    "Name": {
      "title": [
        {
          "type": "text",
          "text": {
            "content": "New Page Title"
          }
        }
      ]
    },
    "Status": {
      "select": {
        "name": "To Do"
      }
    }
  },
  "created_time": "2021-05-22T12:00:00.000Z",
  "last_edited_time": "2021-05-22T12:00:00.000Z",
  "created_by": {
    "object": "user",
    "id": "<user-id>"
  },
  "last_edited_by": {
    "object": "user",
    "id": "<user-id>"
  },
  "icon": null,
  "cover": null,
  "url": "https://www.notion.so/<user-id>/<new-page-id>"
}
```
```

```APIDOC
## PATCH /v1/pages/{page_id}

### Description
Updates a page.

### Method
PATCH

### Endpoint
/v1/pages/{page_id}

### Parameters
#### Path Parameters
- **page_id** (string) - Required - The ID of the page to update.

#### Request Body
- **properties** (object) - Required - The properties to update for the page.

### Request Example
```json
{
  "properties": {
    "Status": {
      "select": {
        "name": "Done"
      }
    }
  }
}
```

### Response
#### Success Response (200)
- **object** (string) - Type of object, "page".
- **id** (string) - The ID of the updated page.
- **properties** (object) - The updated properties of the page.

#### Response Example
```json
{
  "object": "page",
  "id": "<page-id>",
  "title": [
    {
      "type": "text",
      "text": {
        "content": "Sample Page Title"
      }
    }
  ],
  "properties": {
    "Name": {
      "title": [
        {
          "type": "text",
          "text": {
            "content": "Sample Page Title"
          }
        }
      ]
    },
    "Status": {
      "select": {
        "name": "Done"
      }
    }
  },
  "created_time": "2021-05-22T12:00:00.000Z",
  "last_edited_time": "2021-05-22T12:05:00.000Z",
  "created_by": {
    "object": "user",
    "id": "<user-id>"
  },
  "last_edited_by": {
    "object": "user",
    "id": "<user-id>"
  },
  "icon": null,
  "cover": null,
  "url": "https://www.notion.so/<user-id>/<page-id>"
}
```
```

```APIDOC
## GET /v1/pages/{page_id}/properties/{property_id}

### Description
Retrieves a page property item.

### Method
GET

### Endpoint
/v1/pages/{page_id}/properties/{property_id}

### Parameters
#### Path Parameters
- **page_id** (string) - Required - The ID of the page.
- **property_id** (string) - Required - The ID of the property to retrieve.

### Response
#### Success Response (200)
- **object** (string) - Type of object, "property_item".
- **key** (string) - The key of the property.
- **type** (string) - The type of the property.

#### Response Example
```json
{
  "object": "property_item",
  "key": "Status",
  "type": "select",
  "select": {
    "id": "option-1",
    "name": "To Do",
    "color": "default"
  }
}
```
```

--------------------------------

### Search

Source: https://github.com/phacks/notion-ruby-client/blob/main/README.md

Searches all pages and child pages shared with the integration. Results may include databases. Supports query, filter, sort, and pagination.

```APIDOC
## POST /search

### Description
Searches all pages and child pages that are shared with the integration. The results may include databases.

### Method
POST

### Endpoint
/search

### Parameters
#### Query Parameters
- **query** (string) - Optional - Limits which pages are returned by comparing the query to the page title.
- **filter** (object) - Optional - Filters the search results. Example: `{ property: 'object', value: 'page' }`.
- **sort** (object) - Optional - Sorts the results based on the provided criteria. Example: `{ direction: 'ascending', timestamp: 'last_edited_time' }`.
- **start_cursor** (string) - Optional - A cursor to specify the start of the list. Used for pagination.

### Request Body
*Note: The actual request body is determined by the parameters passed to the client method.*

### Request Example
```ruby
client.search # search through every available page and database
client.search(query: 'Specific query')
client.search(filter: { property: 'object', value: 'page' })
client.search(sort: { direction: 'ascending', timestamp: 'last_edited_time' })
client.search(start_cursor: 'fe2cc560-036c-44cd-90e8-294d5a74cebc')
```

### Response
#### Success Response (200)
- **results** (array) - A list of search results (pages or databases).
- **next_cursor** (string) - A cursor to retrieve the next page of results.
- **has_more** (boolean) - Indicates if there are more pages of results.

### Response Example
```json
{
  "object": "list",
  "results": [
    {
      "object": "page",
      "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "title": "Sample Page",
      "last_edited_time": "2023-10-27T10:00:00Z"
    }
  ],
  "next_cursor": "g41e328a-711a-470f-943e-5a8a0f5f2d0d",
  "has_more": true
}
```

### Pagination
See [Pagination](#pagination) for details about how to iterate through the list.
```

--------------------------------

### Databases API

Source: https://github.com/phacks/notion-ruby-client/blob/main/README.md

Endpoints for interacting with Notion databases, including querying, creating, updating, and retrieving database information.

```APIDOC
## POST /v1/databases

### Description
Creates a new database.

### Method
POST

### Endpoint
/v1/databases

### Parameters
#### Request Body
- **title** (object) - Required - The schema of the database.
- **properties** (object) - Required - Properties of the database.

### Request Example
```json
{
  "title": [
    {
      "type": "text",
      "text": {
        "content": "My Database"
      }
    }
  ],
  "properties": {
    "Name": {
      "title": {}
    },
    "Status": {
      "select": {
        "options": [
          {
            "name": "To Do"
          },
          {
            "name": "In Progress"
          },
          {
            "name": "Done"
          }
        ]
      }
    }
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the newly created database.
- **title** (array) - The title of the database.
- **properties** (object) - The properties of the database.

#### Response Example
```json
{
  "object": "database",
  "id": "<database-id>",
  "title": [
    {
      "type": "text",
      "text": {
        "content": "My Database"
      }
    }
  ],
  "properties": {
    "Name": {
      "id": "name",
      "type": "title",
      "title": {}
    },
    "Status": {
      "id": "status",
      "type": "select",
      "select": {
        "options": [
          {
            "id": "option-1",
            "name": "To Do",
            "color": "default"
          },
          {
            "id": "option-2",
            "name": "In Progress",
            "color": "default"
          },
          {
            "id": "option-3",
            "name": "Done",
            "color": "default"
          }
        ]
      }
    }
  },
  "created_time": "2021-05-22T12:00:00.000Z",
  "last_edited_time": "2021-05-22T12:00:00.000Z",
  "created_by": {
    "object": "user",
    "id": "<user-id>"
  },
  "last_edited_by": {
    "object": "user",
    "id": "<user-id>"
  },
  "icon": null,
  "cover": null,
  "url": "https://www.notion.so/<user-id>/<database-id>"
}
```
```

```APIDOC
## POST /v1/query/databases/{database_id}

### Description
Queries a database.

### Method
POST

### Endpoint
/v1/query/databases/{database_id}

### Parameters
#### Path Parameters
- **database_id** (string) - Required - The ID of the database to query.

#### Request Body
- **filter** (object) - Optional - Filter criteria for the query.
- **sorts** (array) - Optional - Sorting criteria for the query.

### Request Example
```json
{
  "filter": {
    "property": "Status",
    "select": {
      "equals": "In Progress"
    }
  },
  "sorts": [
    {
      "property": "Name",
      "direction": "ascending"
    }
  ]
}
```

### Response
#### Success Response (200)
- **object** (string) - Type of object, "list".
- **results** (array) - An array of database entries.
- **next_cursor** (string) - The cursor for the next page of results.
- **has_more** (boolean) - Whether there are more results.

#### Response Example
```json
{
  "object": "list",
  "results": [
    {
      "object": "page",
      "id": "<page-id>",
      "properties": {
        "Name": {
          "title": [
            {
              "type": "text",
              "text": {
                "content": "Task 1"
              }
            }
          ]
        },
        "Status": {
          "select": {
            "name": "In Progress"
          }
        }
      }
    }
  ],
  "next_cursor": null,
  "has_more": false
}
```
```

```APIDOC
## PATCH /v1/databases/{database_id}

### Description
Updates a database.

### Method
PATCH

### Endpoint
/v1/databases/{database_id}

### Parameters
#### Path Parameters
- **database_id** (string) - Required - The ID of the database to update.

#### Request Body
- **title** (object) - Optional - The new title of the database.
- **properties** (object) - Optional - The new properties of the database.

### Request Example
```json
{
  "title": [
    {
      "type": "text",
      "text": {
        "content": "Updated Database Title"
      }
    }
  ]
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the updated database.
- **title** (array) - The updated title of the database.
- **properties** (object) - The updated properties of the database.

#### Response Example
```json
{
  "object": "database",
  "id": "<database-id>",
  "title": [
    {
      "type": "text",
      "text": {
        "content": "Updated Database Title"
      }
    }
  ],
  "properties": {
    "Name": {
      "id": "name",
      "type": "title",
      "title": {}
    },
    "Status": {
      "id": "status",
      "type": "select",
      "select": {
        "options": [
          {
            "id": "option-1",
            "name": "To Do",
            "color": "default"
          },
          {
            "id": "option-2",
            "name": "In Progress",
            "color": "default"
          },
          {
            "id": "option-3",
            "name": "Done",
            "color": "default"
          }
        ]
      }
    }
  },
  "created_time": "2021-05-22T12:00:00.000Z",
  "last_edited_time": "2021-05-22T12:05:00.000Z",
  "created_by": {
    "object": "user",
    "id": "<user-id>"
  },
  "last_edited_by": {
    "object": "user",
    "id": "<user-id>"
  },
  "icon": null,
  "cover": null,
  "url": "https://www.notion.so/<user-id>/<database-id>"
}
```
```

```APIDOC
## GET /v1/databases/{database_id}

### Description
Retrieves a database.

### Method
GET

### Endpoint
/v1/databases/{database_id}

### Parameters
#### Path Parameters
- **database_id** (string) - Required - The ID of the database to retrieve.

### Response
#### Success Response (200)
- **id** (string) - The ID of the database.
- **title** (array) - The title of the database.
- **properties** (object) - The properties of the database.

#### Response Example
```json
{
  "object": "database",
  "id": "<database-id>",
  "title": [
    {
      "type": "text",
      "text": {
        "content": "My Database"
      }
    }
  ],
  "properties": {
    "Name": {
      "id": "name",
      "type": "title",
      "title": {}
    },
    "Status": {
      "id": "status",
      "type": "select",
      "select": {
        "options": [
          {
            "id": "option-1",
            "name": "To Do",
            "color": "default"
          },
          {
            "id": "option-2",
            "name": "In Progress",
            "color": "default"
          },
          {
            "id": "option-3",
            "name": "Done",
            "color": "default"
          }
        ]
      }
    }
  },
  "created_time": "2021-05-22T12:00:00.000Z",
  "last_edited_time": "2021-05-22T12:00:00.000Z",
  "created_by": {
    "object": "user",
    "id": "<user-id>"
  },
  "last_edited_by": {
    "object": "user",
    "id": "<user-id>"
  },
  "icon": null,
  "cover": null,
  "url": "https://www.notion.so/<user-id>/<database-id>"
}
```
```

--------------------------------

### Paginate API Results with Notion Client

Source: https://github.com/phacks/notion-ruby-client/blob/main/README.md

Illustrates how to use the client's built-in cursor pagination for fetching lists of resources, such as users. The client automatically handles pagination tokens and retries on rate limiting. It allows customization of page size, retry attempts, and adding a sleep interval between requests.

```ruby
# Basic pagination
all_users = []
client.users_list(page_size: 25) do |page|
  all_users.concat(page.results)
end

# Pagination with custom retry and sleep interval
all_users = []
client.users_list(sleep_interval: 5, max_retries: 20) do |page|
  all_users.concat(page.results)
end
```

--------------------------------

### List Users

Source: https://github.com/phacks/notion-ruby-client/blob/main/README.md

Retrieves a paginated list of users for the workspace. Supports pagination.

```APIDOC
## GET /users

### Description
Returns a paginated list of Users for the workspace.

### Method
GET

### Endpoint
/users

### Parameters
#### Query Parameters
- **start_cursor** (string) - Optional - A cursor to specify the start of the list. Used for pagination.

### Request Example
```ruby
client.users_list
client.users_list(start_cursor: 'fe2cc560-036c-44cd-90e8-294d5a74cebc')
```

### Response
#### Success Response (200)
- **results** (array) - A list of User objects.
- **next_cursor** (string) - A cursor to retrieve the next page of results.
- **has_more** (boolean) - Indicates if there are more pages of results.

### Response Example
```json
{
  "object": "list",
  "results": [
    {
      "object": "user",
      "id": "f79b2988-7b48-4f2a-a83a-4b7a1b3d8e4f",
      "name": "Jane Doe",
      "avatar_url": "https://example.com/avatar.png",
      "type": "person",
      "person": {
        "email": "jane.doe@example.com"
      }
    }
  ],
  "next_cursor": "g41e328a-711a-470f-943e-5a8a0f5f2d0d",
  "has_more": true
}
```

### Pagination
See [Pagination](#pagination) for details about how to iterate through the list.
```

--------------------------------

### Comments API

Source: https://github.com/phacks/notion-ruby-client/blob/main/README.md

Endpoints for interacting with Notion comments, including retrieving comments from a page or block, and creating comments.

```APIDOC
## GET /v1/comments/{parent_id}

### Description
Retrieves comments from a page or block by ID.

### Method
GET

### Endpoint
/v1/comments/{parent_id}

### Parameters
#### Path Parameters
- **parent_id** (string) - Required - The ID of the page or block to retrieve comments from.

### Response
#### Success Response (200)
- **object** (string) - Type of object, "list".
- **results** (array) - An array of comment objects.
- **next_cursor** (string) - The cursor for the next page of results.
- **has_more** (boolean) - Whether there are more results.

#### Response Example
```json
{
  "object": "list",
  "results": [
    {
      "object": "comment",
      "id": "<comment-id-1>",
      "created_time": "2021-05-22T12:00:00.000Z",
      "created_by": {
        "object": "user",
        "id": "<user-id>"
      },
      "rich_text": [
        {
          "type": "text",
          "text": {
            "content": "This is the first comment."
          }
        }
      ]
    },
    {
      "object": "comment",
      "id": "<comment-id-2>",
      "created_time": "2021-05-22T12:05:00.000Z",
      "created_by": {
        "object": "user",
        "id": "<user-id>"
      },
      "rich_text": [
        {
          "type": "text",
          "text": {
            "content": "This is the second comment."
          }
        }
      ]
    }
  ],
  "next_cursor": null,
  "has_more": false
}
```
```

```text

```

--------------------------------

### Comments API

Source: https://github.com/phacks/notion-ruby-client/blob/main/README.md

Manage comments on Notion pages and discussions. This includes retrieving existing comments and creating new ones.

```APIDOC
## Comments API

### Retrieve comments from a page or block by id

#### Method
GET

#### Endpoint
`/v1/comments?block_id={block_id}`

#### Parameters
##### Query Parameters
- **block_id** (string) - Required - The ID of the block or page to retrieve comments from.

#### Request Example
```ruby
client.retrieve_comments(block_id: '1a2f70ab26154dc7a838536a3f430af4')
```

### Create a comment

#### Method
POST

#### Endpoint
`/v1/comments`

#### Parameters
##### Request Body
- **parent** (object) - Required - An object containing the `page_id` or `discussion_id` where the comment should be created.
  - **page_id** (string) - The ID of the page.
  - **discussion_id** (string) - The ID of the discussion.
- **rich_text** (array) - Required - An array of rich text objects representing the comment content.

#### Request Example (on a page)
```ruby
options = {
  parent: { page_id: '3e4bc91d36c74de595113b31c6fdb82c' },
  rich_text: [
    {
      text: {
        content: 'Hello world'
      }
    }
  ]
}
client.create_comment(options)
```

#### Request Example (on a discussion)
```ruby
options = {
  discussion_id: 'ea116af4839c410bb4ac242a18dc4392',
  rich_text: [
    {
      text: {
        content: 'Hello world'
      }
    }
  ]
}
client.create_comment(options)
```

### Response
#### Success Response (200 for retrieve, 201 for create)
- **Comment object** (object) - The created or retrieved comment object.

#### Response Example (created comment)
```json
{
  "object": "comment",
  "id": "d57e8b2a-4a7f-4a0e-9c3b-5a3a4a3a3a3a",
  "created_time": "2023-01-01T12:00:00.000Z",
  "last_edited_time": "2023-01-01T12:00:00.000Z",
  "created_by": {
    "object": "user",
    "id": "..."
  },
  "parent": {
    "type": "page_id",
    "page_id": "3e4bc91d36c74de595113b31c6fdb82c"
  },
  "rich_text": [
    {
      "type": "text",
      "text": {
        "content": "Hello world",
        "link": null
      }
    }
  ]
}
```
```

--------------------------------

### Retrieve Notion Database with Ruby

Source: https://github.com/phacks/notion-ruby-client/blob/main/README.md

Fetches a specific Notion Database object using its unique identifier. This operation returns the database's metadata and schema. The notion-ruby-client is used to make the API request.

```ruby
client.database(database_id: 'e383bcee-e0d8-4564-9c63-900d307abdb0')
```