Installation
Add to your Gemfile:
gem "administrate-sdk"
Then run bundle install. Requires Ruby 3.1 or later.
Authentication
Create an API key in Settings > Developers, then pass it when initializing the client:
require "administrate-sdk"
client = Administrate.new(
api_key: "sk_live_...",
timeout: 30, # optional, defaults to 30s
max_retries: 3 # optional, defaults to 3
)
Quick start
# Get account info
account = client.account.get
puts "#{account.name} (#{account.plan})"
# List all clients (auto-paginates)
client.clients.list.each do |c|
puts "#{c.name} (#{c.code})"
end
# Get failed executions
client.executions.list(errors_only: true).each do |ex|
puts "#{ex.workflow_name}: #{ex.error_category}"
end
Common operations
Monitor failing workflows
client.executions.list(
status: "failed",
start_date: "2026-01-01",
end_date: "2026-01-31"
).each do |ex|
puts "#{ex.workflow_name}: #{ex.error_category}"
end
Trigger a sync
client.instances.sync("n8n_abc123", sync_type: "all")
Sync all instances at once
client.instances.sync_all(sync_type: "workflows")
Check sync health
client.sync_runs.health.each do |entry|
puts "#{entry.instance_name} (#{entry.sync_status})"
puts " Workflows: #{entry.workflows.last_synced_at}"
puts " Executions: #{entry.executions.last_synced_at}"
end
Auto-pagination
All .list methods handle pagination automatically. You can iterate through all results without worrying about page boundaries:
client.workflows.list(client_id: "com_abc123", active: true).each do |wf|
puts wf.name
end
Retry and backoff
The SDK automatically retries failed requests with exponential backoff using Faraday middleware. Configure the retry count when initializing:
client = Administrate.new(api_key: "sk_live_...", max_retries: 5)
Error handling
begin
client.instances.get("n8n_nonexistent")
rescue Administrate::NotFoundError
puts "Instance not found"
rescue Administrate::AuthenticationError
puts "Invalid API key"
rescue Administrate::RateLimitError => e
puts "Rate limited, retry after #{e.retry_after}s"
end