Ruby SDK
This is a platform SDK — it covers the full Kilimanjaro API surface: data, auth (Gate), migrations, functions, policies, audit, org management, realtime subscriptions, and object storage. A separate mobile SDK family exists for auth-only mobile use cases.
The Ruby SDK gives Ruby 3.2+ applications idiomatic, snake_case access to the full Kilimanjaro platform. It ships RBS signature files so Sorbet and Steep users get static type assistance. The SDK surfaces realtime subscriptions as an enumerator and delivers all errors as K9o::KError exceptions — the same closed error taxonomy across every platform SDK.
- Package:
k9o(RubyGems) - Runtime baseline: Ruby 3.2+
- Error delivery:
raise K9o::KErroron failure (throw-on-error per SDK conventions) - Data-plane record body:
Hash(RBS:Hash[String, untyped])
Installation
Add the gem to your Gemfile:
gem "k9o"
Then run:
bundle install
Or install directly:
gem install k9o
Coordinate: k9o on RubyGems.org.
Setup
Construct the client with org_slug, project_slug, and API key. base_url is optional — it defaults to https://api.k9o.io, and when you also supply org_slug the SDK derives the canonical https://<orgSlug>.api.k9o.io for you. The snippet below shows the explicit subdomain form for clarity; you may omit base_url entirely and let the SDK derive it. Self-hosted and Sovereign deployments pass their own host as base_url.
require "k9o"
k9o = K9o.create_client(
base_url: "https://acme.api.k9o.io", # optional
api_key: ENV["K9O_API_KEY"],
org_slug: "acme",
project_slug: "member-portal",
)Showing example in Ruby
Never hard-code your API key. Read it from an environment variable (K9O_API_KEY is the conventional name) or a secrets manager. The SDK does not infer the org or project from the key — both slugs must be supplied explicitly.
Self-hosted and Sovereign override
For self-hosted or Sovereign Control deployments, pass your own host as base_url instead of the Kilimanjaro Cloud subdomain. The value must be a scheme-plus-host — no path segment:
require "k9o"
k9o = K9o.create_client(
base_url: "https://platform.acme.internal", # scheme + host only; no path
api_key: ENV["K9O_API_KEY"],
org_slug: "acme",
project_slug: "member-portal",
)Showing example in Ruby
Supplying a path-bearing value (e.g. "https://api.your-domain.com/v2") raises K9o::KError with code K9O_INVALID_BASE_URL at instantiation time, before any request is made. Local development with a DevProxy uses "http://localhost:8080".
Getting started
The first operation most applications make is querying a data collection — build a query, execute it, and handle K9o::KError. Signing users in has its own section below.
require "k9o"
k9o = K9o.create_client(
base_url: "https://acme.api.k9o.io", # optional
api_key: ENV["K9O_API_KEY"],
org_slug: "acme",
project_slug: "member-portal",
)
begin
# Query a data collection
response = k9o.from("posts").select().limit(10).execute
response.data.each { |row| puts row }
puts "next cursor: #{response.meta.cursor.next}"
rescue K9o::KError => e
warn "[#{e.code}] #{e.message}: #{e.recommendation}"
end{"id"=>"post_1", "title"=>"Hello"}
next cursor:Showing example in Ruby
What this does:
K9o.create_clientconstructs the client.org_slugandproject_slugdetermine the request subdomain and path;api_keyauthenticates every call.k9o.from("posts").select().limit(10).executeruns a query-builder query against thepostscollection in your project and returns{ data, meta }. Thedatafield is an array ofHashrecords.response.meta.cursor.nextis the opaque pagination cursor for the next page (nilon the final page). See the data API reference for the full pagination model.
Authenticating your End-Users
Gate signs in your project's end users — distinct from the operator credentials you use for the Console. This server SDK covers password sign-in and session management: signIn, signUp, signOut, whoami, and refreshToken. Social-IdP (OAuth2 redirect) and passwordless flows (magic-link / OTP) are browser and mobile flows — see the TypeScript SDK and mobile SDK pages, or the Auth API reference for those and the full Gate surface. revoke_all_sessions ends every session of the signed-in user, this device included; access tokens already issued live until they expire. See Session lifetime and sign-out.
result = k9o.gate.sign_in(email: "[email protected]", password: "…")
puts "signed in: #{result.data['user']['id']}"
puts "access token: #{result.data['session']['accessToken']}"signed in: eu_8f3kQ2mZ
access token: eyJhbGciOiJSUzI1NiIs...Showing example in Password
sign_in returns an envelope whose data is a Hash with user and session; session carries accessToken and refreshToken, and user['id'] is the end-user's platform identifier (eu_<base62>). See the Auth API reference for the full Gate method surface (sign_up, sign_out, refresh_token, whoami, and the session shape).
Handling errors
Every platform failure raises K9o::KError. The exception carries these fields drawn from the wire KError envelope:
| Field | Type | Description |
|---|---|---|
code | String | SCREAMING_SNAKE_CASE error code from the closed taxonomy |
message | String | Human-readable description; safe to log and surface |
context | Hash | Family-specific structured fields (see error catalogue) |
recommendation | String | nil | Remediation hint; nil when there is none |
Switch on e.code for recoverable errors; re-raise anything you did not explicitly handle.
begin
response = k9o.from("events").select.execute
rescue K9o::KError => e
case e.code
when "K9O_TIER_CAP_HIT"
# recommendation is text when present, otherwise nil
warn "Tier cap reached: #{e.message} #{e.recommendation}"
when "K9O_ACCESS_DENIED"
warn "Permission denied: #{e.message}"
when "K9O_INVALID_CREDENTIALS"
warn "Sign-in failed"
else
raise # re-raise unexpected errors
end
endShowing example in Ruby
The full error catalogue — every K9O_* code, its HTTP status, family classification, and per-code context schema — is at /specifications/error-catalogue.
Realtime subscriptions
Realtime events are delivered over Server-Sent Events and exposed as an Enumerator of event hashes. A stream lasts up to 300 seconds; to continue after it ends, reconnect with the last event id as Last-Event-ID and drop duplicates by eventId (the client contract, see the Realtime API reference). There is no initial-state replay: read the current rows first, then subscribe for changes.
k9o.realtime.subscribe(K9o::Realtime::Topic.collection("orders")).each do |event|
puts "#{event['eventType']} #{event['payload']}" # e.g. row_inserted
endrow_inserted {"id"=>"order-124", "total"=>42}
row_deleted {"id"=>"order-124"}Showing example in Ruby
See the data realtime reference for topics and the frame format.
Streams
Streams are ordered and replayable. max_bytes (the second argument to streams.create) is at least 10485760 (10 MiB). The stream's slug (created.data["slug"]) is what the other calls take; the slug of "orders" is orders. subscribe returns an Enumerator and reconnects from the last sequence on its own; leave the loop with break.
k9o.streams.create("orders", 10_485_760)
k9o.streams.publish("orders", { "id" => 1, "total" => 42 }, subject: "eu.new")
k9o.streams.publish("orders", { "id" => 2, "total" => 17 })
k9o.streams.subscribe("orders", from_sequence: 0).each do |event|
puts "#{event['sequence']} #{event['data'].to_json}" # 1 {"id":1,"total":42}
break if event["sequence"].to_s == "2"
end
page = k9o.streams.replay("orders", from_sequence: 0, limit: 10)
puts "#{page.data['events'].length} #{page.data['hasMore']}"1 {"id":1,"total":42}
2 {"id":2,"total":17}
2 falseShowing example in Ruby
See also
- API reference — full platform surface, all endpoints, wire shapes
- Conventions — response envelope, KError shape, pagination, idempotency
- CLI reference — the
k9ocommand-line tool - All SDKs — TypeScript, Python, Go, Rust, Java, Kotlin, .NET, Swift, PHP, Flutter, React Native