Skip to main content
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

ResourceMethods
client.actorget_profile, get_actor_albums/artists/songs/scrobbles/playlists/loved_songs, get_actor_neighbours, get_actor_compatibility
client.albumget_album, get_albums, get_album_tracks
client.apikeyget_apikeys, create_apikey, update_apikey, remove_apikey (auth)
client.artistget_artist, get_artists, get_artist_albums/tracks/listeners/recent_listeners
client.chartsget_scrobbles_chart, get_top_artists, get_top_tracks
client.feedsearch, get_feed_generators/generator/feed, get_stories, get_recommendations, get_artist_recommendations, get_album_recommendations
client.graphfollow_account, unfollow_account, get_followers, get_follows, get_known_followers (auth)
client.likelike_song, dislike_song, like_shout, dislike_shout (auth)
client.mirrorget_mirror_sources, put_mirror_source (auth)
client.playerplay, pause, next, previous, seek, play_file, play_directory, add_items_to_queue, get_currently_playing, get_playback_queue
client.playlistget_playlist, get_playlists, create_playlist, remove_playlist, start_playlist, insert_files, insert_directory
client.scrobblecreate_scrobble, get_scrobble, get_scrobbles
client.shoutcreate_shout, reply_shout, remove_shout, report_shout, get_*_shouts, get_shout_replies
client.songget_song, get_songs, get_song_recent_listeners, match_song, create_song
client.spotifyplay, pause, next, previous, seek, get_currently_playing (auth)
client.statsget_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
ClassStatus
Rocksky::BadRequest400
Rocksky::Unauthorized401
Rocksky::Forbidden403
Rocksky::NotFound404
Rocksky::RateLimited429
Rocksky::ServerError5xx
Rocksky::HTTPErrorany other non-2xx
Rocksky::TransportErrorDNS/TCP/timeouts

​
Configuration

OptionDefaultEnv var
base_urlhttps://api.rocksky.appROCKSKY_BASE_URL
tokennilROCKSKY_TOKEN
headers{}—
user_agentrocksky-ruby/<version>—
open_timeout10 seconds—
read_timeout30 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.

​
License

MIT © Tsiry Sandratraina. Source: sdk/ruby.