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

# Ruby

> The nohead gem: install, configure, and the objects it returns.

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

It needs Ruby 3.3 or newer and uses only Ruby's standard library (Net::HTTP, JSON, OpenSSL). Use it on servers: API keys are secrets. The [overview](https://docs.nohead.io/sdks/overview.md) covers reading and writing, retries, errors, uploads and webhooks, with examples in every language.

## Configure the client

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

nohead = Nohead::Client.new(
  api_key: ENV.fetch("NOHEAD_API_KEY"), # the default
  timeout: 10, # seconds per attempt
  max_retries: 3
)
```

| Option | Default | |
| - | - | - |
| `api_key:` | `NOHEAD_API_KEY` | A project [API key](https://docs.nohead.io/guides/api-keys.md). Required. |
| `project_id:` | the key's project | Looked up once with `GET /v1/me` when omitted. |
| `max_retries:` | `2` | See [retries](https://docs.nohead.io/sdks/overview.md#retries-and-idempotency). |
| `timeout:` | `60` | Seconds per attempt. |
| `headers:` | `{}` | Added to every request. |
| `warnings:` | `true` | Warns about deprecated operations and plan usage, once each. |

API keys belong to a project, so methods like `collections.list` need no project ID, and collections can be named by ID or slug.

## Results

The API's resources come back as `Nohead::NoheadObject`s:

* **Read fields** with methods (`record.data`) or `[]` (`record[:data]`, `record["data"]`), at any depth. Fields named like Ruby's own methods (`method`, `hash`) need `[]`.
* **Timestamps** (`created_at`, `purge_after`, a scheduled change's `at`) are `Time`s. A record's field values in `data` stay as they come.
* **Unknown fields are kept,** because the API adds fields and values without notice. `to_h` gives the raw Hash.

## Images

`Nohead::Images.url` builds an image URL with resizing options: see [Images](https://docs.nohead.io/guides/images.md#frameworks).

## Methods

Every method follows a resource of the API: `records`, `drafts`, `collections`, `fields`, `migrations`, `assets`, `webhooks`, `search`, `audit_events` and more. Each endpoint in the [API reference](https://docs.nohead.io/api-reference/overview.md) shows its call in Ruby, and the [README](https://github.com/nohead-io/nohead-ruby#reference) lists them by resource.

## Source

The SDK is open source, under the MIT license. Report issues and follow releases on GitHub:


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.