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

# Content moderation with Ruby

> Learn how to moderate content using Moderation API's Ruby SDK

***

<Snippet file="prerequisites.mdx" />

***

## 1. Install the SDK

<CodeGroup>
  ```bash gem theme={"theme":"nord"}
  gem install moderation_api
  ```

  ```bash bundler theme={"theme":"nord"}
  # Add this to your Gemfile
  gem 'moderation_api', '~> 2.0.0'

  # Then run
  bundle install
  ```
</CodeGroup>

<Note>
  Requires Ruby 3.2.0 or higher.
</Note>

## 2. Submit content

Grab the API key from your [project](https://dash.moderationapi.com) and begin submitting text, images, or other media to your project for moderation.

<CodeGroup>
  ```ruby Text moderation theme={"theme":"nord"}
  require "moderation_api"

  # Initialize the client with your secret key
  moderation_api = ModerationAPI::Client.new(
    secret_key: ENV["MODAPI_SECRET_KEY"] || "your-api-key"
  )

  # Submit text for moderation
  response = moderation_api.content.submit(
    content: {
      type: "text",
      text: "Hello world!"
    },
    author_id: "123",
    conversation_id: "456",
    metadata: {
      custom_field: "value"
    }
  )

  # Check if content was flagged
  if response.evaluation.flagged
    puts "Content was flagged"
  end

  # Act on the recommendation
  case response.recommendation.action
  when :allow
    puts "Text content is safe."
    # Save to database or proceed...
  when :review
    puts "Text content needs review"
    # Send to review queue
  when :reject
    puts "Text content rejected"
    # Block the content, show an error, etc...
  end
  ```

  ```ruby Image moderation theme={"theme":"nord"}
  require "moderation_api"

  # Initialize the client with your secret key
  moderation_api = ModerationAPI::Client.new(
    secret_key: ENV["MODAPI_SECRET_KEY"] || "your-api-key"
  )

  # Submit image for moderation
  response = moderation_api.content.submit(
    content: {
      type: "image",
      url: "https://example.com/image.jpg"
    },
    author_id: "123",
    conversation_id: "456",
    metadata: {
      custom_field: "value"
    }
  )

  # Check if content was flagged
  if response.evaluation.flagged
    puts "Image was flagged"
  end

  # Act on the recommendation
  case response.recommendation.action
  when :allow
    puts "Image is safe."
    # Save to database or proceed...
  when :review
    puts "Image needs review"
    # Send to review queue
  when :reject
    puts "Image rejected"
    # Block or require review
  end
  ```

  ```ruby Object moderation theme={"theme":"nord"}
  require "moderation_api"

  # Initialize the client with your secret key
  moderation_api = ModerationAPI::Client.new(
    secret_key: ENV["MODAPI_SECRET_KEY"] || "your-api-key"
  )

  # Submit object for moderation
  response = moderation_api.content.submit(
    content: {
      type: "object",
      data: {
        name: {
          type: "text",
          text: "John Doe"
        },
        email: {
          type: "text",
          text: "john.doe@example.com"
        },
        picture: {
          type: "image",
          url: "https://example.com/image.jpg"
        }
      }
    },
    author_id: "123",
    conversation_id: "456",
    metadata: {
      custom_field: "value"
    }
  )

  # Check if content was flagged
  if response.evaluation.flagged
    puts "Object was flagged"
  end

  # Act on the recommendation
  case response.recommendation.action
  when :allow
    puts "Object is safe."
    # Save to database or proceed...
  when :review
    puts "Object needs review"
    # Send to review queue
  when :reject
    puts "Object rejected"
    # Block or require review
  end
  ```
</CodeGroup>

## 3. Handle errors

The SDK throws specific error types for different scenarios:

```ruby theme={"theme":"nord"}
require "moderation_api"

moderation_api = ModerationAPI::Client.new(
  secret_key: ENV["MODAPI_SECRET_KEY"] || "your-api-key"
)

begin
  response = moderation_api.content.submit(
    content: {
      type: "text",
      text: "Hello world!"
    }
  )

  puts "Recommendation: #{response.recommendation.action}"

rescue ModerationAPI::Errors::BadRequestError => e
  puts "Invalid request: #{e.message}"
rescue ModerationAPI::Errors::AuthenticationError => e
  puts "Authentication failed: #{e.message}"
rescue ModerationAPI::Errors::RateLimitError => e
  puts "Rate limit exceeded: #{e.message}"
rescue ModerationAPI::Errors::APIConnectionError => e
  puts "Connection error: #{e.message}"
rescue ModerationAPI::Errors::APITimeoutError => e
  puts "Request timed out: #{e.message}"
rescue ModerationAPI::Errors::InternalServerError => e
  puts "Server error: #{e.message}"
end
```

<Note>
  The SDK automatically retries failed requests up to 2 times by default. Configure retries globally with `max_retries: 0` when initializing the client, or per-request using `request_options: {max_retries: 5}`. Timeouts default to 60 seconds and can be customized similarly.
</Note>

***

<Snippet file="dry-run.mdx" />

***

<Snippet file="review-flagged.mdx" />

***

<Snippet file="all-done.mdx" />