anakin-ruby

Official Ruby SDK for Anakin — web scraping, crawling, search, and Wire actions.

Status: alpha (v0.1.x). Public API may change between minor versions until v1.0.

Install

gem install anakin-sdk

Or add to your Gemfile:

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

Requires Ruby 2.7+.

Quickstart

require 'anakin'

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

doc = client.scrape('https://example.com')
puts doc['markdown']

The SDK polls long-running jobs internally — you get the final result back from a single synchronous method call. No job IDs to manage, no polling loops to write.

Method overview

Method Endpoint Sync?
client.scrape(url, **opts) POST /url-scraper → poll async
client.map(url, **opts) POST /map → poll async
client.crawl(url, **opts) POST /crawl → poll async
client.search(query, **opts) POST /search sync
client.agentic_search(prompt, **opts) POST /agentic-search → poll async
client.wire(action_id, params) POST /holocron/task → poll async
client.sessions.list / create / save / update / delete /browser-sessions/* various
Anakin.supported_countries offline (bundled) sync

Configuration

client = Anakin.new(
  api_key: 'ak-...',                   # or ANAKIN_API_KEY env var
  base_url: 'https://api.anakin.io/v1',
  timeout: 60,                         # per-request seconds
  max_retries: 4,                      # on 429 / 5xx / transient
  poll_interval: 1,                    # initial polling delay (seconds)
  poll_max_interval: 10,               # capped backoff (seconds)
  poll_timeout: 300,                   # total poll budget (seconds)
)

Errors

Every error raised by the SDK is a subclass of Anakin::Error:

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 "unknown error: #{e.message}"
end

The error 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

Development

git clone https://github.com/Anakin-Inc/anakin-ruby
cd anakin-ruby
bundle install
rake test

License

Apache 2.0