Etherpad Lite Ruby Client

The etherpad-lite Ruby Gem is a Ruby client for Etherpad Lite's HTTP JSON API. Etherpad Lite is a collaborative editor provided by the Etherpad Foundation.

See for information on how to install and configure your own Etherpad Lite instance, and read for an in-depth description of Etherpad Lite's HTTP API.


gem install etherpad-lite

NOTE Nobody likes you, Ruby 1.8. Now go away.

Basic usage

require 'etherpad-lite'

# Connect to your Etherpad Lite instance
ether = EtherpadLite.connect('', 'the api key', '1.2.1')

# Get a Pad (or create one if it doesn't exist)
pad = ether.pad('my first etherpad lite pad')

puts pad.text
=> "Welcome to Etherpad Lite!\n\nThis pad text is synchronized as you type, so that everyone viewing..."

# Write your the changes to the Pad
pad.text = "What hath God wrought?"

# There are now 2 revisions!
puts pad.revision_numbers
=> [0, 1]

# Iterate through each revision
pad.revisions.each do |pad_rev|
  puts "Revision #{pad_rev.rev}:"
  puts pad_rev.text

Advanced usage

The above example deals with public pads, accessible to anyone through the Web UI. There is another class of pads - group pads - which deal with groups, authors and sessions. Examples are documented in EtherpadLite::Group, EtherpadLite::Author, and EtherpadLite::Session.

Example use in Rails

For your view, I recommend the jQuery plugin at Also, I recommend reading the docs for EtherpadLite::Group first.

Add the following to your Gemfile

gem 'etherpad-lite'

On login, create a Hash in your session to store EtherpadLite API sessions:

session[:ep_sessions] = {}

Some example controller actions:

class EtherpadController < ApplicationController
  # /etherpad
  def index
    # Your users are probably members of some kind of groups.
    # These groups can be mapped to EtherpadLite Groups. List all the user's groups.
    @app_groups = current_user.groups

  # /etherpad/groups/:id
  def group
    ether = EtherpadLite.connect(9001,'/srv/www/etherpad-lite/APIKEY.txt'))
    @app_group = YourAppGroup.find(params[:id])
    # Map your app's group to an EtherpadLite Group, and list all its pads
    group ="my_app_group_#{}")
    @pads = group.pads

  # /etherpad/pads/:ep_group_id/:ep_pad_name
  def pad
    ether = EtherpadLite.connect(9001,'/srv/www/etherpad-lite/APIKEY.txt'))
    # Get the EtherpadLite Group and Pad by id
    @group = ether.get_group(params[:ep_group_id])
    @pad = @group.pad(params[:ep_pad_name])
    # Map the user to an EtherpadLite Author
    author ="my_app_user_#{}", name:
    # Get or create an hour-long session for this Author in this Group
    sess = session[:ep_sessions][] ? ether.get_session(session[:ep_sessions][]) : @group.create_session(author, 60)
    if sess.expired?
      sess = @group.create_session(author, 60)
    session[:ep_sessions][] =
    # Set the EtherpadLite session cookie. This will automatically be picked up by the jQuery plugin's iframe.
    cookies[:sessionID] = {value:, domain: ""}

Low-level client

There is an optional low-level client, which is a paper-thin wrapper around Etherpad Lite's HTTP JSON API. In the examples above, the low-level client is accessible from the high-level interface:

client = ether.client
client.getText(padID: 'my first etherpad lite pad')
=> {:text => "What hath God wrought?"}

or you can explicitly load just the low-level client:

require 'etherpad-lite/client'
client = EtherpadLite.client('', 'api key', 1.1)
client.setText(padID: 'my first etherpad lite pad', text: "lots of new text and stuff")

The methods and parameters exactly match the HTTP API. For a full list of them, see


Testing this library is fairly simple. It requires:

  • A recent version of Rspec

  • A running copy of Etherpad Lite with a fresh db for each run of the tests (configure connection in spec/config.yml)

Bring up Etherpad Lite with:

rm var/dirty.db && bin/

Run the tests with

rspec spec


Copyright 2011 Jordan Hollinger

Licensed under the Apache License


This Ruby client was inspired by TomNomNom’s PHP client and devjones’s Python client.