Ruby SDK

Official Ruby SDK for Anakin (anakin.io)

Official Ruby gem for the Anakin API. Wraps every documented endpoint with a single sync call, internal polling, and a typed error hierarchy. Pure stdlib — no runtime dependencies.


Status	Alpha (v0.1.x)
Language	Ruby 2.7+
Gem name	`anakin-sdk` on RubyGems
Source	github.com/Anakin-Inc/anakin-ruby
License	Apache 2.0

Install

gem install anakin-sdk

Or in your Gemfile:

gem 'anakin-sdk', '~> 0.1'

Quickstart

require 'anakin'

client = Anakin.new(api_key: 'ak-...')  # or set ANAKIN_API_KEY env var

# Scrape a single URL — returns the final result, no polling required
doc = client.scrape('https://example.com')
puts doc['markdown']

# Discover URLs on a site
sitemap = client.map('https://example.com', limit: 200)
puts sitemap['links']

# Crawl pages and get content for each
crawl = client.crawl('https://example.com', max_pages: 20)
crawl['pages'].each do |page|
  puts "#{page['url']}: #{(page['markdown'] || '').length}"
end

What's in v0.1

Method	Returns
`client.scrape(url, **opts)`	`Hash` — the document
`client.map(url, **opts)`	`Hash` — discovered links
`client.crawl(url, **opts)`	`Hash` — crawled pages
`client.search(query, **opts)`	`Hash` — search results (synchronous API)
`client.agentic_search(prompt, **opts)`	`Hash` — AI-synthesised answer
`client.wire(action_id, params)`	`Hash` — Wire action result (run a Wire action)
`client.sessions.list / create / save / update / delete`	Browser session CRUD

All response methods return parsed JSON as Ruby Hash/Array. Strict struct types via Anakin::Document, Anakin::CrawlResult etc. are on the v0.2 roadmap.

Configuration

client = Anakin.new(
  api_key:           'ak-...',                    # or ANAKIN_API_KEY env var
  base_url:          'https://api.anakin.io/v1',
  timeout:           60,                          # per-request HTTP timeout (seconds)
  max_retries:       4,                           # retries on 429 / 5xx
  poll_interval:     1.0,                         # initial polling delay
  poll_max_interval: 10.0,                        # cap on exponential backoff
  poll_timeout:      300,                         # total wait before JobTimeoutError
)

Errors

require 'anakin'

begin
  doc = client.scrape('https://example.com')
rescue Anakin::InsufficientCreditsError => e
  puts "out of credits: balance=#{e.balance}, needed=#{e.required}"
rescue Anakin::AuthenticationError
  puts "invalid API key — get a fresh one at anakin.io/dashboard"
rescue Anakin::RateLimitError => e
  puts "rate limited; retry after #{e.retry_after}s"
rescue Anakin::JobFailedError => e
  puts "job failed: #{e.reason}"
rescue Anakin::Error => e
  puts "anakin error: #{e.message}"
end

The hierarchy:

Class	When
`Anakin::AuthenticationError`	401 — invalid or missing API key
`Anakin::InsufficientCreditsError`	402 — out of credits (`#balance`, `#required`)
`Anakin::InvalidRequestError`	400 — validation failure
`Anakin::RateLimitError`	429 — after retry budget exhausted (`#retry_after`)
`Anakin::JobFailedError`	Polled job came back with `status="failed"` (`#reason`)
`Anakin::JobTimeoutError`	Polling budget exhausted before terminal status
`Anakin::ServerError`	5xx — after retries exhausted
`Anakin::NetworkError`	DNS / connect / read-timeout
`Anakin::Error`	Base class; everything above inherits from it

Stability

v0.1.x is alpha. The public API may change between minor versions until v1.0. Pin a specific version in production:

gem 'anakin-sdk', '0.1.0'

Raise issues on GitHub.