Ruby

rocksky is a stdlib-only Ruby client for the Rocksky API.

client = Rocksky.new(token: ENV["ROCKSKY_TOKEN"])

client.actor.get_profile(did: "tsiry-sandratraina.com")
client.charts.get_top_artists(limit: 10, start_date: "2025-01-01")
client.scrobble.create_scrobble(title: "In Bloom", artist: "Nirvana")

Every XRPC NSID maps to a method on a resource object. app.rocksky.actor.getProfile becomes client.actor.get_profile(...). app.rocksky.scrobble.createScrobble becomes client.scrobble.create_scrobble(...). Kwargs in, parsed JSON out.

Install

# Gemfile
gem "rocksky"

gem install rocksky

Requires Ruby 3.0+. Depends only on Ruby’s stdlib (net/http, json, uri).

Quick start

require "rocksky"

# Reads ROCKSKY_BASE_URL and ROCKSKY_TOKEN from the env when omitted.
client = Rocksky.new

profile = client.actor.get_profile(did: "tsiry-sandratraina.com")
puts profile["displayName"]

For authenticated calls, pass a bearer token:

client = Rocksky.new(token: "eyJ...")
client.scrobble.create_scrobble(title: "In Bloom", artist: "Nirvana")

with_token derives a new client without mutating the original — handy when a single base client is shared across users in a web app:

base = Rocksky.new
def for_user(base, token) = base.with_token(token)

Resources

Resource	Methods
`client.actor`	`get_profile`, `get_actor_albums/artists/songs/scrobbles/playlists/loved_songs`, `get_actor_neighbours`, `get_actor_compatibility`
`client.album`	`get_album`, `get_albums`, `get_album_tracks`
`client.apikey`	`get_apikeys`, `create_apikey`, `update_apikey`, `remove_apikey` (auth)
`client.artist`	`get_artist`, `get_artists`, `get_artist_albums/tracks/listeners/recent_listeners`
`client.charts`	`get_scrobbles_chart`, `get_top_artists`, `get_top_tracks`
`client.feed`	`search`, `get_feed_generators/generator/feed`, `get_stories`, `get_recommendations`, `get_artist_recommendations`, `get_album_recommendations`
`client.graph`	`follow_account`, `unfollow_account`, `get_followers`, `get_follows`, `get_known_followers` (auth)
`client.like`	`like_song`, `dislike_song`, `like_shout`, `dislike_shout` (auth)
`client.mirror`	`get_mirror_sources`, `put_mirror_source` (auth)
`client.player`	`play`, `pause`, `next`, `previous`, `seek`, `play_file`, `play_directory`, `add_items_to_queue`, `get_currently_playing`, `get_playback_queue`
`client.playlist`	`get_playlist`, `get_playlists`, `create_playlist`, `remove_playlist`, `start_playlist`, `insert_files`, `insert_directory`
`client.scrobble`	`create_scrobble`, `get_scrobble`, `get_scrobbles`
`client.shout`	`create_shout`, `reply_shout`, `remove_shout`, `report_shout`, `get_*_shouts`, `get_shout_replies`
`client.song`	`get_song`, `get_songs`, `get_song_recent_listeners`, `match_song`, `create_song`
`client.spotify`	`play`, `pause`, `next`, `previous`, `seek`, `get_currently_playing` (auth)
`client.stats`	`get_stats`, `get_wrapped`

For anything not covered:

client.query("app.rocksky.actor.getProfile", did: "did:plc:7vdlgi2bflelz7mmuxoqjfcr")
client.procedure("app.rocksky.like.likeSong", body: { uri: "at://..." })

Conventions

Keyword args for every parameter. Ruby snake_case maps to the lexicon’s camelCase (start_date: → startDate).
nil is dropped. Pass nil for any optional param and it won’t be sent.
Arrays are CSV-joined. Lexicon list params accept Ruby arrays.
Hashes in, hashes out. Responses come back as plain Hash (string keys), mirroring the lexicon JSON 1:1.

Errors

begin
  client.song.get_song(uri: "at://does-not-exist")
rescue Rocksky::NotFound => e
  puts "missing: #{e.message} (status=#{e.status}, nsid=#{e.nsid})"
rescue Rocksky::RateLimited
  sleep 5; retry
rescue Rocksky::Error => e
  warn "rocksky failure: #{e.class}: #{e.message}"
end

Class	Status
`Rocksky::BadRequest`	400
`Rocksky::Unauthorized`	401
`Rocksky::Forbidden`	403
`Rocksky::NotFound`	404
`Rocksky::RateLimited`	429
`Rocksky::ServerError`	5xx
`Rocksky::HTTPError`	any other non-2xx
`Rocksky::TransportError`	DNS/TCP/timeouts

Configuration

Option	Default	Env var
`base_url`	`https://api.rocksky.app`	`ROCKSKY_BASE_URL`
`token`	`nil`	`ROCKSKY_TOKEN`
`headers`	`{}`	—
`user_agent`	`rocksky-ruby/<version>`	—
`open_timeout`	`10` seconds	—
`read_timeout`	`30` seconds	—

IRB console

$ gem install rocksky
$ ROCKSKY_TOKEN=eyJ... rocksky-console
Rocksky 0.2.0 — interactive console
  base_url : https://api.rocksky.app
  token    : present (set via ROCKSKY_TOKEN)

irb> client.actor.get_profile(did: "did:plc:7vdlgi2bflelz7mmuxoqjfcr")
=> {"did"=>"did:plc:...", "handle"=>"tsiry-sandratraina.com", ...}

Types

Lexicon-derived Struct types are available under Rocksky::Generated::*, mirroring every lex *View* / *Record / *Input / *Output / *Params shape from the Rocksky lexicons. Regenerate with bun run lexgen:types at the repo root.

Overview

Language SDKs

Install

Quick start

Resources

Conventions

Errors

Configuration

IRB console

Types

License

​Install

​Quick start

​Resources

​Conventions

​Errors

​Configuration

​IRB console

​Types

​License

Install

Quick start

Resources

Conventions

Errors

Configuration

IRB console

Types

License