Configuration

All three SDKs share the same configuration surface — option names follow each language's conventions (snake_case for Ruby and Python, camelCase for JavaScript).

Apidepth.configure do |config|
  config.api_key     = ENV["APIDEPTH_API_KEY"]
  config.environment = "production"
  config.sample_rate = 0.5
end

Options

Option	Type	Default	Description
api_keyrequired	String	nil	Your Apidepth API key. Required — events are dropped silently if absent.
environment	String	"production"	Tag applied to every event. Appears in the dashboard environment switcher.
enabled	Boolean	true	Set to false to disable all instrumentation. Useful for test environments.
flush_interval	Integer	20	Seconds between background batch flushes. Lower values reduce dashboard latency; higher values reduce HTTP overhead.
sample_rate	Float (0.0–1.0)	1.0	Fraction of events to capture. 1.0 captures everything; 0.1 captures ~10%.
ignored_hosts	Array<String>	[]	Additional hostnames to exclude. Supports exact strings and glob wildcards (e.g. *.internal). localhost, 127.0.0.1, 0.0.0.0, ::1, and the collector URL are always ignored.
extra_vendors	Hash<String,String>	{}	Custom vendor mappings: { "vendor-name" => "api.hostname.com" }. Appears alongside built-in vendors.
collector_url	String	https://collector.apidepth.io/v1/events	Override the event ingest endpoint. Must be HTTPS. Useful for self-hosted deployments.
registry_refresh_interval	Integer	21600 (6 h)	Seconds between background vendor registry refreshes.
registry_cache_path	String	/tmp/apidepth_registry.json	Absolute path for the on-disk registry cache. Must not contain '..' traversal segments.
capture_model_names	Boolean	true	Read the model field from AI vendor JSON responses (OpenAI, Anthropic, Gemini, Mistral, Cohere) to power the Model Radar page. Set to false to disable body access entirely.
on_flush_error	Proc \| nil	nil	Called with (error, context) when a batch flush fails. Use to forward to Sentry, Honeybadger, etc.

Flush error callback

on_flush_error is called when the background thread fails to deliver a batch after retries. Use it to surface failures to your error tracker:

Apidepth.configure do |config|
  config.api_key = ENV["APIDEPTH_API_KEY"]

  config.on_flush_error = ->(error, context) {
    Sentry.capture_exception(error, extra: context)
  }
end

The callback receives:

error — the exception that caused the failure
context — an object/hash/dict with dropped_events, consecutive_failures, and total_dropped

Custom logger

By default Apidepth uses Rails.logger. To route SDK logs elsewhere:

Apidepth.logger = Logger.new(STDOUT)
Apidepth.logger.level = Logger::WARN   # suppress DEBUG output

# Silence all SDK output:
Apidepth.logger = nil

Ignored hosts and glob patterns

The SDK always ignores localhost, 127.0.0.1, 0.0.0.0, ::1, and the collector URL itself. Use ignored_hosts to add your own patterns. Glob wildcards are supported:

Apidepth.configure do |config|
  config.api_key        = ENV["APIDEPTH_API_KEY"]
  config.ignored_hosts  = [
    "*.internal",
    "*.svc.cluster.local",
    "internal-api.example.com",
  ]
end

Sample rate

sample_rate is a float between 0.0 and 1.0. At 1.0 (default) every outgoing request is recorded. At 0.5, roughly half are sampled. Sampling is random and applied per-request.

Rate limit header data (rl_remaining, etc.) is always captured when present, even on sampled-out events — quota snapshots are updated regardless of sample_rate.

Registry cache

The SDK fetches a vendor registry from the collector on startup and refreshes it in the background every registry_refresh_interval seconds. The registry is written to registry_cache_path so cold starts can skip the network fetch.

The cache path must be an absolute path with no .. traversal. Default is /tmp/apidepth_registry.json. If your /tmp is not writable (e.g. read-only container images), override it:

config.registry_cache_path = "/var/cache/apidepth/registry.json"

CLI reference

All three SDKs ship two CLI subcommands. Run either with --help / -h for full usage.

`apidepth setup`

Interactive wizard that detects your framework, generates the correct initializer snippet, and optionally writes it to disk. Fully non-interactive in CI with --no-prompt.

Flag	Description
--api-key <key>	Inject your Apidepth API key directly into the generated snippet.
--no-prompt	Non-interactive mode — skip all questions and print the snippet to stdout. Required for CI/CD pipelines.
--framework <name>	Override auto-detection. Accepted values: rails, sinatra, django, fastapi, express, nextjs. Auto-detection checks project files (Gemfile, manage.py, next.config.js, etc.).
--ignored-hosts <patterns>	Comma-separated list of host patterns to add to the snippet's ignoredHosts / ignored_hosts list. Glob wildcards supported (e.g. *.internal,api.private).
--collector-url <url>	Override the collector URL in the generated snippet. Useful for self-hosted deployments.
--help, -h	Print usage and exit.

`apidepth test`

Sends a synthetic test event to the collector and confirms the pipeline is working. The event is flagged test: true and never appears in vendor data or alerts. Exits with code 1 on any error and prints a per-failure-mode message with next steps.

Flag	Description
(no flags)	Reads APIDEPTH_API_KEY and APIDEPTH_COLLECTOR_URL from the environment (or from your initializer if already loaded). Sends one synthetic event and prints the round-trip time on success.
--help, -h	Print usage and exit.