Docs›Configuration

Configuration

Detection rules, custom patterns, provider keys, automatic fallback, zero-data mode, and action types.

Overview

Grepture configuration lives in your dashboard. Detection rules determine what gets flagged, and actions determine what happens when a rule matches. Everything is managed through the dashboard UI — no configuration files or code changes needed.

Operating modes

The SDK supports two modes — set via the mode option in the constructor:

• +Proxy mode ("proxy", default) — requests route through the Grepture proxy. Detection rules, PII redaction, blocking, and prompt management all run before traffic reaches the provider. Use this when you need to inspect or modify requests in flight.
• +Trace mode ("trace") — requests go directly to the provider with no proxy in the path. The SDK captures metadata (model, tokens, latency, cost) asynchronously and sends it to the dashboard. Use this for observability and cost tracking without latency overhead — ideal for real-time agents, streaming UIs, and high-throughput pipelines.

Both modes share the same dashboard: traffic log, cost tracking, and conversation tracing all work regardless of mode. The difference is that trace mode entries don't have rules_applied since no rules ran.

See Operating modes in the SDK reference for setup examples.

Detection rules

Rules define what patterns Grepture looks for in your API traffic. Each rule has conditions (what to match) and actions (what to do).

Regex-based detection (all plans)

High-performance pattern matching that runs in under 1ms. Detects structured data like:

• +PII — emails, phone numbers, SSNs, dates of birth, addresses
• +Secrets — API keys, bearer tokens, database connection strings, OAuth tokens
• +Financial — credit card numbers, bank account numbers, routing numbers
• +Network — IP addresses, MAC addresses, URLs with credentials

The free plan includes 50+ built-in regex patterns. All patterns are open source and auditable. Free plans are limited to 3 rules; Pro and above get unlimited rules.

AI-powered detection (all plans)

All five AI detection actions are available on every plan, including Free. Free users get 25 AI-powered requests per month (shared across all AI action types). Pro and Business plans get unlimited AI usage according to their tier.

The following AI models all run on Grepture infrastructure — no data leaves to external AI services.

AI PII detection (Free: sampling, Pro+: unlimited)

Local AI models that detect unstructured personal data that regex can't catch:

• +Names — first names, last names, full names in natural language
• +Locations — cities, countries, addresses in freeform text
• +Organizations — company names, institutions

Prompt injection detection (Free: sampling, Business+: unlimited)

Detects and blocks adversarial prompt injection attempts before they reach your LLM. Configurable threshold scoring with the option to block or log detections.

Additional AI detection (Free: sampling, Business+: unlimited)

• +Toxicity detection — toxic, obscene, threatening, or hateful content
• +DLP (Data Loss Prevention) — source code, credentials, internal documents, financial data
• +Compliance detection — healthcare, financial, legal, and insurance domain violations

AI sampling (Free plan)

Free users can configure rules with any AI action. The proxy enforces a shared pool of 25 AI requests per calendar month. When the limit is reached, AI actions silently skip — the request still goes through, just without AI-powered protection. Track your usage in the dashboard billing settings or via the X-Grepture-AI-Sampling response header.

Actions

When a rule matches, Grepture takes one or more actions. Each rule can have multiple actions configured.

Creating rules

In the dashboard, navigate to Rules and click Create Rule:

1. +Name — a descriptive identifier (e.g., block-credit-cards)
2. +Apply to — where to run the rule: input (request), output (response), or both
3. +Conditions — match criteria using field + operator + value:
   • +Fields: header, model, body, url
   • +Operators: contains, equals, matches (regex), exists
   • +Multiple conditions can be combined with AND or OR logic
4. +Actions — one or more actions to take when conditions match
5. +Sampling rate — percentage of matching requests to apply the rule to (0–100)
6. +Priority — execution order when multiple rules match (drag to reorder in the rules list)

Provider keys

Store your LLM provider API keys in the Grepture dashboard instead of passing them on every request. The proxy resolves keys automatically — no X-Grepture-Auth-Forward header needed.

Supported providers

OpenAI, Anthropic, Google Gemini, and Azure OpenAI. Add multiple keys per provider.

Key management

Navigate to Settings > API > Provider Keys in the dashboard:

1. +Click Add key and select a provider
2. +Enter your API key (encrypted with AES-256-GCM before storage)
3. +Optionally set a default model (required for cross-provider fallback)
4. +Optionally link a fallback key — another key to try if this one fails

The first key added for a provider becomes the primary automatically. Promote a different key to primary with one click (the previous primary is demoted). If the primary key is deleted, the next oldest key is auto-promoted.

Only the last 4 characters of each key are visible in the dashboard. Plaintext keys exist only in process memory at request time — they are never cached or logged.

Using stored keys

When a request arrives without an X-Grepture-Auth-Forward header, the proxy looks up the primary key for the target provider and uses it. If the caller supplies the header, the stored key is bypassed and the caller's key is used directly.

Provider fallback

Define fallback chains so the proxy automatically retries failed requests with different keys or providers.

Same-provider fallback

Link multiple keys for the same provider in a chain. When the primary key fails, the proxy tries the next key. Useful for distributing usage across rate-limit buckets or keeping backup keys for redundancy.

Cross-provider fallback

A fallback key can belong to a different provider. If all OpenAI keys fail, the proxy can automatically try an Anthropic key. Cross-provider fallback translates the request format (e.g., OpenAI chat completions to Anthropic messages) and translates the response back. Your application receives a response in the original provider's format.

Cross-provider fallback requires a default_model on the fallback key so the proxy knows which model to target. Tool calls and standard message formats are translated. Image inputs skip cross-provider translation.

Fallback triggers

Fallback is triggered on these HTTP status codes:

Fallback is not triggered on:

• +400 — Bad request (your payload is malformed — retrying won't help)
• +403 — Content policy violation (key-specific)
• +404 — Model or endpoint not found

Streaming caveat

Once a streaming response has started sending data (headers sent, chunks flowing), the proxy cannot retry. Fallback works for errors that occur before streaming begins — this covers the vast majority of cases since auth errors, rate limits, and server errors return before streaming starts.

Cycle detection

The dashboard prevents circular fallback chains (A → B → C → A). Each key can only appear once in a chain.

Trace visibility

Every fallback attempt is logged in the dashboard with the provider_key_id. See the full chain: which key was tried, what error came back, and which provider ultimately served the request.

Zero-data mode

Enable zero-data mode and Grepture processes every request without persisting any content:

• +Request and response bodies stay in memory only
• +Headers, URLs, and query parameters are never stored
• +Detection rules still fire — PII detection, redaction, blocking all work in-flight
• +Only operational metadata is logged: HTTP method, status code, latency, and rule hits

Toggle zero-data mode in the dashboard on the API settings page. Available on Business plans and above.

Fallback mode

Configure what happens if the Grepture proxy encounters an internal error:

• +Passthrough — forward the raw request to the target API (prioritizes availability)
• +Error — return a 502 error to your application (prioritizes security)

Configure fallback mode on the API settings page in the dashboard.