---
title: "Ruby"
description: "Official CarsXE SDK for Ruby."
canonical_url: "https://docs.carsxe.com/docs/sdks/ruby"
markdown_url: "https://docs.carsxe.com/docs/sdks/ruby.md"
last_updated: "1980-01-01"
---

# Ruby
URL: /docs/sdks/ruby
LLM index: /llms.txt
Description: Official CarsXE SDK for Ruby.

The `carsxe` gem is the official CarsXE client for Ruby. It wraps the REST API with idiomatic methods and handles authentication. Requires Ruby 2.7 or later.

## Installation

Add to your Gemfile:

```ruby
gem 'carsxe'
```

Or install directly:

```bash
gem install carsxe
```

## Quick start

```ruby
require "carsxe"

carsxe = Carsxe::CarsXE.new(api_key: ENV["CARSXE_API_KEY"])

begin
  vehicle = carsxe.specs({ "vin" => "WBAFR7C57CC811956" })
  puts vehicle
rescue StandardError => error
  puts "Error: #{error.message}"
end
```

## Methods

### Core

| Method | Description |
|---|---|
| `specs(params)` | Decode a 17-character VIN into full vehicle specifications |
| `market_value(params)` | Retail, trade-in, and auction value estimates |
| `recalls(params)` | Open safety recalls by VIN, make, model, or year |
| `plate_decoder(params)` | VIN lookup from a license plate (50+ countries) |
| `history(params)` | Title events, salvage, junk, and insurance records |

### Bulk recall batch

| Method | Description |
|---|---|
| `submit_bulk_recall_batch(params)` | Submit a batch of VINs for recall lookup |
| `get_bulk_recall_batch_status(batch_id)` | Poll job status |
| `get_bulk_recall_batch_results(batch_id)` | Retrieve completed results |
| `get_bulk_recall_batch_download_url(batch_id)` | Get a CSV download URL |

## Error handling

The client raises `StandardError` on API errors. Wrap calls in a `begin/rescue` block:

```ruby
begin
  vehicle = carsxe.specs({ "vin" => "WBAFR7C57CC811956" })
  puts vehicle
rescue StandardError => error
  puts "Error: #{error.message}"
end
```

## Best practices

**Load your key from the environment.** Use `ENV.fetch` to surface misconfiguration immediately:

```ruby
carsxe = Carsxe::CarsXE.new(api_key: ENV.fetch("CARSXE_API_KEY"))
```

**Create one instance and reuse it** across requests — the client manages the underlying connection pool.

**Store your key in an environment variable.** Never hardcode it or commit it to source control.

```bash
# .env
CARSXE_API_KEY=your_key_here
```

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).