monday_ruby

A Ruby client library for the monday.com GraphQL API. Build integrations with boards, items, columns, and more using idiomatic Ruby.

Features

• Resource-based API - Clean, intuitive interface (client.board.query, client.item.create)
• Flexible configuration - Global or per-client setup
• Comprehensive error handling - Typed exceptions for different error scenarios
• Cursor-based pagination - Efficiently handle large datasets
• Fully tested - 100% test coverage with VCR-recorded fixtures

Documentation

Complete Documentation →

• Getting Started Tutorial
• How-to Guides
• API Reference
• Best Practices

Installation

Add to your Gemfile:

gem "monday_ruby"

Or install directly:

gem install monday_ruby

Quick Start

require "monday_ruby"

# Configure with your API token
Monday.configure do |config|
  config.token = ENV["MONDAY_TOKEN"]
end

# Create a client
client = Monday::Client.new

# Query boards
response = client.board.query(args: { limit: 5 })

if response.success?
  boards = response.body.dig("data", "boards")
  boards.each { |board| puts board["name"] }
end

Get your API token from your monday.com Admin settings.

Usage

Configuration

Global configuration (recommended):

Monday.configure do |config|
  config.token = ENV["MONDAY_TOKEN"]
  config.version = "2024-01"  # API version (optional)
end

client = Monday::Client.new

Per-client configuration:

client = Monday::Client.new(
  token: ENV["MONDAY_TOKEN"],
  version: "2024-01"
)

Configure timeouts:

Monday.configure do |config|
  config.token = ENV["MONDAY_TOKEN"]
  config.open_timeout = 10  # seconds (default: 10)
  config.read_timeout = 30  # seconds (default: 30)
end

Working with Boards

# Query boards
response = client.board.query(
  args: { ids: [1234567890] },
  select: ["id", "name", "description"]
)

boards = response.body.dig("data", "boards")

# Create a board
response = client.board.create(
  args: {
    board_name: "Project Tasks",
    board_kind: "public",
    description: "Track project deliverables"
  }
)

board = response.body.dig("data", "create_board")

Working with Items

# Create an item
response = client.item.create(
  args: {
    board_id: 1234567890,
    item_name: "Implement authentication",
    column_values: {
      status: { label: "Working on it" },
      date4: { date: "2024-12-31" }
    }
  }
)

# Query items
response = client.item.query(
  args: { ids: [987654321] },
  select: ["id", "name", { column_values: ["id", "text"] }]
)

items = response.body.dig("data", "items")

Pagination

Handle large datasets efficiently with cursor-based pagination:

# Fetch first page
response = client.board.items_page(
  board_ids: 1234567890,
  limit: 100
)

items = response.body.dig("data", "boards", 0, "items_page", "items")
cursor = response.body.dig("data", "boards", 0, "items_page", "cursor")

# Fetch next page
if cursor
  next_response = client.board.items_page(
    board_ids: 1234567890,
    limit: 100,
    cursor: cursor
  )
end

See the Pagination Guide for more details.

Error Handling

The library provides typed exceptions for different error scenarios:

begin
  response = client.board.query(args: { ids: [123] })
rescue Monday::AuthorizationError => e
  puts "Invalid API token: #{e.message}"
rescue Monday::InvalidRequestError => e
  puts "Invalid request: #{e.message}"
rescue Monday::RateLimitError => e
  puts "Rate limit exceeded: #{e.message}"
rescue Monday::Error => e
  puts "API error: #{e.message}"
end

See the Error Handling Guide for best practices.

Available Resources

The client provides access to all monday.com resources:

• Boards - client.board
• Items - client.item
• Columns - client.column
• Files - client.file
• Groups - client.group
• Updates - client.update
• Subitems - client.subitem
• Workspaces - client.workspace
• Folders - client.folder
• Account - client.account
• Activity Logs - client.activity_log
• Board Views - client.board_view

For complete API documentation, see the API Reference.

Development

Running Tests

bundle exec rake spec

Tests use VCR to record HTTP interactions, so you don't need a monday.com API token to run them.

Linting

bundle exec rake rubocop

All Checks

bundle exec rake  # Runs both tests and linter

Contributing

Bug reports and pull requests are welcome on GitHub.

Please read our Contributing Guide for details on:

• Development setup and testing
• Documentation guidelines
• Code style and commit conventions

This project follows the Contributor Covenant Code of Conduct.

License

The gem is available as open source under the terms of the MIT License.