adadiamonds

Official Ruby client for the Ada Diamonds API: live lab grown diamond inventory, engagement ring settings, fine jewelry, showrooms, and the diamond buying guides.

Standard library only (net/http, json). Ruby 2.6 or newer.

• Documentation: https://www.adadiamonds.com/developers
• REST reference: https://www.adadiamonds.com/developers/api
• OpenAPI 3.1: https://www.adadiamonds.com/openapi.json
• MCP server (for tool use instead of HTTP): https://www.adadiamonds.com/mcp

gem install adadiamonds

or in a Gemfile:

gem "adadiamonds"

Reading the catalog needs no account and no API key (120 requests per minute). An API key raises that to 600 and unlocks the write endpoints. Every price is in US dollars.

require "adadiamonds"

client = AdaDiamonds::Client.new # anonymous
page = client.diamonds(shape: "Oval", min_carat: 1, max_price: 4000, sort: "price_asc")
page.each do |stone|
  puts [stone["carat"], stone["shape"], stone["price"]].join(" ")
end
p client.last_rate_limit # #<struct limit=120, remaining=119, reset=58, policy="...">

An engagement ring is a setting plus a loose diamond, priced separately. Setting prices never include the center stone.

setting = client.engagement_rings(shape: "Oval", type: "Solitaire", limit: 1).first
stone = client.diamonds(shape: "Oval", min_carat: 1.5, max_carat: 1.6, sort: "price_asc", limit: 1).first
puts setting["priceFrom"] + stone["price"] # US dollars

key = AdaDiamonds::Client.new.create_key("my-agent", env: "sandbox")
client = AdaDiamonds::Client.new(api_key: key["api_key"]) # 600 requests/min

begin
  client.request_consultation(
    { "email" => "test@example.com", "topic" => "engagement_ring" },
    idempotency_key: "consult-42" # a retry cannot create two requests
  )
rescue AdaDiamonds::Error => e
  puts [e.status, e.code, e.description, e.retry_after].inspect
end

Sandbox keys (ada_test_*) return well-formed responses and contact nobody.

answer = client.ask("oval lab diamond engagement ring under $6,000")

Every method maps to one endpoint under /api/v1. For endpoints without a helper, get and post take a path relative to /api/v1 (or absolute on the site) and return the decoded JSON:

bands = client.get("/jewelry", category: "wedding-bands")

List methods return an AdaDiamonds::Page (data, pagination, total, has_more?, and Enumerable). Errors are AdaDiamonds::Error with status, code, description, documentation_url, and retry_after. Every response's RateLimit-* headers are available from last_rate_limit; pace yourself rather than retrying into a 429.

Identify your agent with AdaDiamonds::Client.new(user_agent: "my-agent/1.0 (+https://example.com)"). Bulk scraping of the HTML catalog is not permitted; this API and POST /api/v1/exports are the supported way to read it. Diamond inventory changes continuously; re-check a stone before quoting it.

bundle install
bundle exec rake test

MIT. Copyright Ada Diamonds, Inc.