Skip to main content

Ruby SDK

note

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::KError on 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.

Ruby
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:

Ruby
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.

Ruby
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
Output · bash
{"id"=>"post_1", "title"=>"Hello"}
next cursor:

Showing example in Ruby

What this does:

  • K9o.create_client constructs the client. org_slug and project_slug determine the request subdomain and path; api_key authenticates every call.
  • k9o.from("posts").select().limit(10).execute runs a query-builder query against the posts collection in your project and returns { data, meta }. The data field is an array of Hash records.
  • response.meta.cursor.next is the opaque pagination cursor for the next page (nil on 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.

Password
result = k9o.gate.sign_in(email: "[email protected]", password: "…")
puts "signed in: #{result.data['user']['id']}"
puts "access token: #{result.data['session']['accessToken']}"
Output · bash
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:

FieldTypeDescription
codeStringSCREAMING_SNAKE_CASE error code from the closed taxonomy
messageStringHuman-readable description; safe to log and surface
contextHashFamily-specific structured fields (see error catalogue)
recommendationString | nilRemediation hint; nil when there is none

Switch on e.code for recoverable errors; re-raise anything you did not explicitly handle.

Ruby
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
end

Showing 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.

Ruby
k9o.realtime.subscribe(K9o::Realtime::Topic.collection("orders")).each do |event|
puts "#{event['eventType']} #{event['payload']}"   # e.g. row_inserted
end
Output · bash
row_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.

Ruby
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']}"
Output · bash
1 {"id":1,"total":42}
2 {"id":2,"total":17}
2 false

Showing example in Ruby


See also​

  • API reference — full platform surface, all endpoints, wire shapes
  • Conventions — response envelope, KError shape, pagination, idempotency
  • CLI reference — the k9o command-line tool
  • All SDKs — TypeScript, Python, Go, Rust, Java, Kotlin, .NET, Swift, PHP, Flutter, React Native