Ruby SDK

A small client you can copy into your backend. This is a documented implementation, not a separately published package. It sends the same API envelope for every service through one call method.

Ruby 2.5+; standard library only.

Response contract

Field	Meaning
data	Operation result; absent on API errors
error	API error object, or null/nil on success; message is the stable code
meta	Response metadata, including pagination when returned
exec_time	Gateway execution time in seconds, when returned

API errors return in Result.error. Network, invalid JSON, and transport failures raise an exception or return a Go error. These small clients do not manage sessions, auto-refresh tokens, or retry requests. Pass a current user bearer token to the constructor/client only when acting as that user; omit it for trusted server/agent calls. Keep keys on the server.

Client implementation

Save as singlebase.rb. Download the source.

require 'json'
require 'net/http'
require 'uri'

Result = Struct.new(:data, :error, :meta, :exec_time, keyword_init: true)

class SinglebaseClient
  def initialize(api_key:, api_url:, bearer: nil)
    @api_key, @api_url, @bearer = api_key, api_url, bearer
  end

  def call(operation:, payload:, options: nil)
    uri = URI(@api_url)
    request = Net::HTTP::Post.new(uri)
    request['Content-Type'] = 'application/json'
    request['X-API-KEY'] = @api_key
    request['Authorization'] = "Bearer #{@bearer}" if @bearer
    body = {operation: operation, payload: payload}
    body[:options] = options unless options.nil?
    request.body = JSON.generate(body)
    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = uri.scheme == 'https'
    http.open_timeout = 30
    http.read_timeout = 30
    response = http.request(request)
    decoded = JSON.parse(response.body)
    unless decoded.is_a?(Hash)
      raise 'Expected a JSON API envelope'
    end
    if response.code.to_i >= 400 && !decoded['error']
      raise "HTTP #{response.code} without an API error envelope"
    end
    Result.new(data: decoded['data'], error: decoded['error'], meta: decoded['meta'] || {}, exec_time: decoded['exec_time'])
  end
end

Example

Set SINGLEBASE_API_URL to the complete console endpoint and SINGLEBASE_API_KEY to your server or appropriately scoped agent key. The notes collection must exist.

require_relative 'singlebase'
sbc = SinglebaseClient.new(api_key: ENV.fetch('SINGLEBASE_API_KEY'), api_url: ENV.fetch('SINGLEBASE_API_URL'))
resp = sbc.call(operation: 'data.query', payload: {collection: 'notes', limit: 5}, options: {})
raise resp.error['message'] if resp.error
puts resp.data.inspect
puts resp.meta.inspect
puts resp.exec_time

Use the same method with llm.summarize for generation or chat.ask for an answer, with the operation's verified payload. The options argument goes in the request envelope, separate from payload. An empty options object is valid; omit it when unused. See API overview for request access and errors, and API reference for the operation groups.