> ## Documentation Index
> Fetch the complete documentation index at: https://docs.incident.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Ruby SDK

> Call the incident.io API from Ruby with a method for every endpoint and a class for every request and response.

The Ruby SDK gives you a client for the whole incident.io API. There's a method for every endpoint and a class for every request and response, all generated from our OpenAPI specification. Requiring it is quick: models load the first time you use them, rather than all at once.

It requires Ruby 3.0 or later.

## Installing

```bash theme={null}
gem install incident_io_api
```

Or in your `Gemfile`:

```ruby theme={null}
gem "incident_io_api"
```

The gem is called `incident_io_api`, but the library is `require "incident_io"`, and everything lives under the `IncidentIo` module.

## Your first request

You'll need an API key from **Settings > API keys** (see [API keys](/admin/api-keys)). Then:

```ruby theme={null}
require "incident_io"

IncidentIo.configure do |config|
  config.access_token = ENV.fetch("INCIDENT_API_KEY")
end

result = IncidentIo::IncidentsV2Api.new.incidents_v2_list(page_size: 25)
result.incidents.each do |incident|
  puts "#{incident.reference} #{incident.name}"
end
```

## How endpoints work

Each API resource has a class, such as `IncidentsV2Api` or `AlertsV2Api`, with one method per endpoint. Path parameters and request bodies are positional arguments, and everything optional goes in a trailing hash:

```ruby theme={null}
api = IncidentIo::IncidentsV2Api.new
incident = api.incidents_v2_show("01FDAG4SAP5TYPT98WGR2N7W91").incident
```

If you need the status code or headers, every method has a `_with_http_info` twin:

```ruby theme={null}
data, status, headers = api.incidents_v2_list_with_http_info(page_size: 25)
```

## Pagination

List endpoints are cursor-paginated. Read the next cursor from `pagination_meta.after` and pass it back as `after`:

```ruby theme={null}
after = nil
loop do
  page = api.incidents_v2_list(page_size: 100, after: after)
  page.incidents.each { |incident| puts incident.reference }

  after = page.pagination_meta&.after
  break if after.nil?
end
```

## Filtering

Filters that take an operator are nested hashes:

```ruby theme={null}
api.incidents_v2_list(status_category: { one_of: ["live"] })
```

## Errors

A failed request raises a subclass of `IncidentIo::ApiError` for its status code, so you can rescue the cases you care about and let the rest through:

```ruby theme={null}
begin
  api.incidents_v2_show("does-not-exist")
rescue IncidentIo::NotFoundError
  puts "no such incident"
rescue IncidentIo::ApiError => e
  puts "#{e.code} #{e.error_type}: #{e.errors.map { |err| err["message"] }.join(", ")}"
  puts "request ID for support: #{e.request_id}"
end
```

The subclasses are `BadRequestError` (400), `AuthenticationError` (401), `PermissionDeniedError` (403), `NotFoundError` (404), `ConflictError` (409), `UnprocessableEntityError` (422), `RateLimitError` (429), and `ServerError` (5xx). Network failures and timeouts raise `ApiError` itself, with a `code` of `nil`. When you hit the [rate limit](/api-reference/introduction#rate-limits), `RateLimitError#retry_after` tells you how many seconds to wait.

## Configuration

`IncidentIo.configure` sets the defaults every API class uses. If you need more than one configuration in a process, build an `ApiClient` and pass it in:

```ruby theme={null}
config = IncidentIo::Configuration.new
config.access_token = "my-api-key"
config.timeout = 30 # seconds; the default is 60

client = IncidentIo::ApiClient.new(config)
client.user_agent = "my-app/1.0.0" # identify your integration

api = IncidentIo::IncidentsV2Api.new(client)
```

The client is built on Faraday. `config.configure_faraday_connection { |conn| ... }` gives you the connection, so you can add middleware such as retries or logging.

## Enum values

Fields the API documents as an enum are plain strings in this SDK, and the documentation lists the known values. We add enum values as a backwards-compatible change, and plain strings mean a value newer than your installed gem never breaks the response.

## Deprecated endpoints

Endpoints we've deprecated stay available, but they're marked `@deprecated` in the documentation and warn when called. Ruby hides deprecation warnings by default, so run with `ruby -W:deprecated`, or set `Warning[:deprecated] = true`, to see them.

## Versioning

The SDK is kept up to date with the API automatically. Additions to the API are minor versions. A change that would break your code, like a removed field, is released as a new major version, and its release notes list what changed.

## Resources

<CardGroup cols={2}>
  <Card title="RubyGems" icon="gem" href="https://rubygems.org/gems/incident_io_api">
    The `incident_io_api` gem and its versions.
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/incident-io/sdk-ruby">
    Source, README, and issues for the Ruby SDK.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/introduction">
    Endpoints, authentication, rate limits, and errors.
  </Card>

  <Card title="All SDKs" icon="cubes" href="/integrations/sdks">
    Clients for Go, TypeScript, Python, Rust, PHP, and .NET.
  </Card>
</CardGroup>