API Reference

RED has no JSON API for errors, and no HTTP endpoint that accepts them. Its HTTP routes are the dashboard itself: HTML pages, the forms on them that post back, and one JSON route, the health check for an uptime monitor. This page lists those routes, for when you script the dashboard, put it behind a proxy, or want to know why a request was refused. Errors reach RED from Ruby code running in your app; the Ruby API covers that.

1. Sending errors to RED
2. HTTP routes
3. Ruby API

Sending errors to RED

• Unhandled exceptions in requests and background jobs are captured without any code.
• From your own Ruby code: report a rescued exception with Rails.error.report. Report something that isn’t a Ruby exception with ManualErrorReporter.report.
• From a browser or a mobile app: RED has no endpoint for them. Add a route to your own app that receives the error and calls ManualErrorReporter.report. The Mobile App Integration guide has a complete controller.

HTTP routes

Mount path

The installer mounts the dashboard at /red, and every path below is relative to that mount: /errors means /red/errors. Apps first installed before 0.5.8 are mounted at /error_dashboard instead (see Old mount path). Your config/routes.rb has the real value:

mount RailsErrorDashboard::Engine => "/red"

Authentication

Every route except the issue-tracker webhooks needs the dashboard’s authentication:

• HTTP Basic with the dashboard credentials, ERROR_DASHBOARD_USER and ERROR_DASHBOARD_PASSWORD (see Dashboard Credentials). A missing or wrong login gets 401.
• Your config.authenticate_with block, when you set one. It replaces HTTP Basic. A false result gets 403 with the body Access Denied, and so does a block that raises.

Formats

Pages render HTML only. Asking a page for another format, with .json on the path or an Accept: application/json header, gets 406. The actions that change something are form POSTs that answer with a redirect. Three routes differ: /health answers in JSON, ai_help streams server-sent events, and the webhooks answer with an empty body.

Posting from a script

The dashboard’s forms are protected against cross-site request forgery. A POST needs the session cookie and the token from a page the same session loaded, so a plain curl -X POST -u ... gets 422. To script an action, load a page first, keep its cookie, and send its token:

BASE=https://your-app.example.com/red
JAR=$(mktemp)

# 1. Load a page: it sets the session cookie and carries the token
TOKEN=$(curl -s -u "$RED_USER:$RED_PASSWORD" -c "$JAR" "$BASE/errors" \
  | sed -n 's/.*name="csrf-token" content="\([^"]*\)".*/\1/p')

# 2. Post with the same cookie and the token
curl -s -o /dev/null -w '%{http_code}\n' -u "$RED_USER:$RED_PASSWORD" -b "$JAR" \
  --data-urlencode "authenticity_token=$TOKEN" \
  --data-urlencode "resolved_by_name=deploy-bot" \
  "$BASE/errors/42/resolve"
# => 302

Rate limiting

Rate limiting is off by default. Turn it on in the initializer; it takes effect at boot:

config.enable_rate_limiting = true
config.rate_limit_per_minute = 300 # the default

• What is counted: each client IP gets rate_limit_per_minute requests per minute to each path, counted per exact path, so /red/errors/1 and /red/errors/2 have separate counts. Webhooks and requests that fail authentication count too, because the limit runs before authentication.
• Which paths: the mount path and every path below it (/red and /red/...). Your app’s own paths that only start with the same letters, such as /redirect, aren’t counted; before 0.15.0 they were. With the dashboard mounted at /, every path is counted.
• Over the limit: 429 with an HTML page, Retry-After: 60, X-RateLimit-Limit and X-RateLimit-Period. There is no JSON variant.
• Where counts live: in Rails.cache. With :null_store, nothing is ever limited. With more than one process (Puma workers, or several servers), each process counts on its own unless the cache store is shared, such as Redis, Solid Cache or Memcached. Counting isn’t atomic, so under many concurrent requests the limit is approximate.

Response codes

Until a request is authenticated, these error responses are plain text with no details.

Pages

All are GET. Pages that take days accept 1 to 365 and default to 30, except Platform Comparison (7). Pages that list rows take page and per_page (default 25, at most 100: a larger value, however it is written, such as 150.5 or 0999, is capped). application_id limits most pages to one application.

When a page’s option is off, the page redirects to /errors with a message saying the feature is off; the Needs column gives the option. The LLM health page is the exception: it renders and says the feature is off.

Health check

GET /health answers in JSON whether the dashboard can still record and show errors, for an uptime monitor. It needs the dashboard’s authentication like every other route, because the body names your database adapter and queue backend.

curl -s -u "$RED_USER:$RED_PASSWORD" https://your-app.example.com/red/health

{
  "status": "ok",
  "version": "0.15.0",
  "timestamp": "2026-10-15T08:34:14Z",
  "checks": {
    "database": { "status": "ok", "adapter": "PostgreSQL", "separate_database": false, "tables_present": true, "latency_ms": 0.42 },
    "errors": { "status": "ok", "last_error_at": "2026-10-15T08:07:00Z", "last_24h": 41 },
    "queue": { "status": "ok", "async_logging": true, "adapter": "solid_queue", "problems": [] },
    "storm_protection": { "status": "ok", "enabled": true, "state": "closed" },
    "active_storage": { "status": "ok", "service": "amazon", "latency_ms": 48.3 }
  },
  "duration_ms": 1.9
}

• database checks the error database, so with a separate one, that is what’s tested. Only this check can make the answer down. While it fails, errors is skipped.
• active_storage makes one existence check against your storage service, and says skipped when ActiveStorage isn’t set up.
• The answer has Cache-Control: no-store. If the check itself fails, the answer is still JSON, {"status":"down", "version": ..., "error": "<exception class>"}, with 503.

Actions on one error

All are POST /errors/:id/<action>. All except ai_help redirect back to the error.

An invalid value (an unknown status, a priority of 4, hours=0) changes nothing. The redirect carries a message saying why.

Priority and status

status is one of new, in_progress, investigating, resolved and wont_fix. update_status allows only these moves:

Moving to resolved this way resolves the error and runs the same callbacks, event and plugins as the Resolve button. A wont_fix error still counts new occurrences, but sends no notifications for them.

Other actions

All are POST.

batch_action takes action_type:

The list page offers only Resolve and Delete. IDs that don’t exist are skipped.

Issue-tracker webhooks

POST /webhooks/:provider, where :provider is github, gitlab, codeberg or linear. When someone closes a linked issue, RED resolves the error; when they reopen it, RED reopens the error.

These routes skip the dashboard’s login and CSRF check. They check a signature made with config.issue_webhook_secret instead:

• 404 unless enable_issue_tracking is on and issue_webhook_secret is set.
• 401 for a missing or wrong signature, and for a Linear delivery whose webhookTimestamp is missing or more than 60 seconds from the server’s clock, as Linear’s docs recommend. Keep the server’s clock synced.
• 404 for any other provider.
• 200 once those checks pass, even when the payload matches no error or fails to process, so the tracker doesn’t retry.

Webhooks RED sends

With enable_webhook_notifications and webhook_urls, RED POSTs JSON to your URLs (see the Notifications guide). Set config.webhook_signing_secret, or WEBHOOK_SIGNING_SECRET, and every POST is signed:

The timestamp is part of what is signed, so a captured request can’t be replayed with a new one. A Ruby receiver can check both with RailsErrorDashboard::Services::WebhookSigner.valid?(body, timestamp:, signature:, secret:), which also refuses a timestamp more than 300 seconds off (tolerance:). See Signing for receivers in other languages.

Filtering the error list

GET /errors takes these query parameters. Each takes a single value.

Unknown values for severity, timeframe, frequency and sort_by are ignored.

curl -s -u "$RED_USER:$RED_PASSWORD" \
  "https://your-app.example.com/red/errors?platform=iOS&severity=critical&timeframe=last_7_days&hide_muted=1"

This returns the HTML page.

Ruby API

These are the parts of RED meant to be called from your app.

Configuration

RailsErrorDashboard.configure do |config|
  config.enable_slack_notifications = true
end

Every option is in the Configuration Guide.

Rails.error.report

RED subscribes to the Rails error reporter, so this records a rescued exception:

begin
  charge_card!
rescue PaymentGateway::Declined => e
  Rails.error.report(e, handled: false, context: { user_id: current_user.id })
  # ...
end

Pass handled: false or severity: :error. RED skips reports that are handled warnings, which is what Rails.error.handle { } sends, and on Rails 7.1 and later a bare Rails.error.report(e) too (on Rails 7.0, handled: is required). Rails.error.record { } reports and re-raises, and RED records it.

ManualErrorReporter.report

Records an error that isn’t a Ruby exception, such as one sent by a browser or a mobile app:

RailsErrorDashboard::ManualErrorReporter.report(
  error_type: "TypeError",
  message: "Cannot read properties of undefined (reading 'id')",
  backtrace: [ "at renderCart (cart.js:42)", "at onClick (button.js:15)" ],
  platform: "Web",
  user_id: current_user&.id,
  app_version: "2.1.0",
  metadata: { component: "ShoppingCart" }
)

It returns the RailsErrorDashboard::ErrorLog, or nil. It returns nil when config.async_logging is on (a job saves the error), and when the error is ignored, sampled out or held back by storm protection.

Callbacks and notifications

Run your own code when RED records or resolves an error:

# config/initializers/rails_error_dashboard.rb, after the configure block
RailsErrorDashboard.on_error_logged do |error_log|
  Rails.logger.info("RED: #{error_log.error_type}")
end

RailsErrorDashboard.on_critical_error do |error_log|
  # ...
end

RailsErrorDashboard.on_error_resolved do |error_log|
  # ...
end

• on_error_logged runs for a new error and for a resolved error that happens again, but not for each repeat of an open error. An open error that keeps happening more than 24 hours after RED first recorded it starts a new error record, so it runs again then. on_critical_error runs at the same moments when the error is critical.
• on_error_resolved runs whenever an error is resolved: the Resolve button, a batch resolve, a status change to resolved, ErrorLog#resolve! or a webhook.
• A callback that raises is rescued and doesn’t stop the others.

The same moments are published as ActiveSupport::Notifications events: error_logged.rails_error_dashboard, critical_error.rails_error_dashboard and error_resolved.rails_error_dashboard. Each payload has error_log and error_id.

ActiveSupport::Notifications.subscribe("error_logged.rails_error_dashboard") do |event|
  StatsD.increment("errors.#{event.payload[:severity]}")
end

For more events (every recurrence, mute, unmute, each batch action, and the error page being viewed), write a plugin. See the Plugin System.

Breadcrumbs

RailsErrorDashboard.add_breadcrumb("checkout started", { cart_id: cart.id })

It adds a step to the current request’s trail. It does nothing unless config.enable_breadcrumbs is on. See Manual Breadcrumbs.

Jobs

RED’s periodic jobs need your scheduler: see Schedule the periodic jobs. Since 0.15.0, cascade detection is one of them: RailsErrorDashboard::CascadeDetectionJob, which does nothing while enable_error_cascades is off.

RailsErrorDashboard::CascadeDetectionJob.perform_now(lookback_hours: 1)
# => { detected: 2, updated: 5 }

Keep lookback_hours equal to the time between runs: each run adds 1 to the frequency of every cascade it finds again, so windows that overlap count the same errors twice (see Scheduling). With Solid Queue, in config/recurring.yml:

production:
  red_cascades:
    class: RailsErrorDashboard::CascadeDetectionJob
    args: [ { lookback_hours: 1 } ]
    schedule: every hour

Reading and changing errors

Errors are RailsErrorDashboard::ErrorLog records, stored in RED’s database (your primary database, or the separate one if you set that up).

errors = RailsErrorDashboard::ErrorLog.unresolved.by_platform("iOS").last_24_hours

error = RailsErrorDashboard::ErrorLog.find(42)
error.error_type        # "NoMethodError"
error.occurrence_count  # 17
error.severity          # :critical, :high, :medium or :low
error.critical?

error.resolve!(resolved_by_name: "deploy-bot", resolution_comment: "Fixed in #456")
error.mute!(muted_by: "ops", reason: "Known, fix scheduled")
error.unmute!

Scopes: unresolved, resolved, recent, by_error_type, by_platform, by_environment, by_status, by_priority, by_assignee, assigned, unassigned, active (not snoozed), snoozed, muted, unmuted, last_24_hours, last_week.

resolve! works like the Resolve button, including the callbacks. mute! and unmute! work like their buttons.

Internal classes

The Commands, Queries and Services classes back the dashboard’s pages. They aren’t a public API and can change in any release. If you already call them, these are their current signatures:

The source is in lib/rails_error_dashboard/ and app/models/rails_error_dashboard/.