Froddy RCL — API Reference

API version: v1 · Base URL: https://froddy.io · Last updated: February 2026

Table of Contents

1. Authentication
2. Evaluate Transaction — the core endpoint
3. Decision Log
4. Policy Management
5. Rules
6. Statistics
7. Alerting — Telegram (Optional)
8. Alerting — Webhook
9. Entity Overrides
10. Sensitivity Analysis
11. Pilot Report
12. Health Check
13. Tenant Management (Admin)
14. Idempotency
15. Error Handling
16. Timeouts & Latency
17. Rate Limits
18. Versioning & Compatibility
19. Webhook Delivery
20. Access Level Summary

Authentication

All endpoints except /health and the demo tenant require the X-API-Key header.

X-API-Key: your_tenant_api_key

Each tenant receives a unique API key during provisioning. The key identifies both the caller and the tenant scope — all data returned is isolated to that tenant.

Demo tenant: The demo tenant is publicly accessible without an API key. It is intended for evaluation and interactive demos at froddy.io/demo. Do not use it for production data.

Admin endpoints (tenant management) require a separate admin key passed via the same X-API-Key header.

Evaluate Transaction

The core endpoint. Call this before each payout to receive a verdict.

[TENANT] POST /v1/evaluate

Request

curl -X POST https://froddy.io/v1/evaluate \
  -H "X-API-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "payout_12345",
    "entity_id": "partner_42",
    "amount": 15000.00,
    "currency": "USD",
    "event_type": "payout",
    "device_hash": "abc123def456"
  }'

Request Schema

Response — ALLOW

{
  "event_id": "payout_12345",
  "verdict": "allow",
  "rule_id": null,
  "reason": "All rules passed",
  "evaluated_at": "2026-02-20T14:30:00"
}

Response — HOLD

{
  "event_id": "payout_12345",
  "verdict": "hold-for-review",
  "rule_id": "R-CEIL",
  "reason": "daily ceiling exceeded: $53,000 / $50,000",
  "evaluated_at": "2026-02-20T14:30:00"
}

Response — BLOCK

{
  "event_id": "payout_12345",
  "verdict": "block",
  "rule_id": "R-COHORT",
  "reason": "single transaction $150,000 >= block threshold $100,000",
  "evaluated_at": "2026-02-20T14:30:00"
}

Response Schema

Note: The response does not include decision_id, policy_version, or shadow fields. The event_id serves as the decision identifier. Shadow mode status can be checked via the health endpoint.

Verdict Values

Rule Evaluation Order

Rules are evaluated in fixed priority: R-COHORT → R-CEIL → R-VEL → R-DEDUP. The first rule to trigger determines the verdict. If no rule triggers, the verdict is allow.

For rule parameters and default thresholds, see Policy Management and the Rules Reference in the product docs.

Decision Log

Query the log of all evaluation decisions for this tenant.

List Decisions

[TENANT] GET /v1/decisions

Returns a list of past evaluation decisions with filtering support.

Query Parameters:

Example:

curl -X GET "https://froddy.io/v1/decisions?verdict=block&entity_id=partner_42" \
  -H "X-API-Key: your_key"

Example response:

{
  "decisions": [
    {
      "id": 42,
      "event_id": "payout_12345",
      "entity_id": "partner_42",
      "amount": 15000.0,
      "currency": "USD",
      "event_type": "payout",
      "event_ts": "2026-02-20T14:30:00",
      "tenant": "demo",
      "scenario": "default",
      "verdict": "hold-for-review",
      "rule_id": "R-CEIL",
      "rule_snapshot": "{\"daily_total\": 53000, \"ceiling_usd\": 50000}",
      "reason": "daily ceiling exceeded: $53,000 / $50,000",
      "evaluated_at": "2026-02-20T14:30:01",
      "device_hash": null
    }
  ],
  "count": 1
}

Export Decisions

[TENANT] GET /v1/decisions/export

Exports decisions in JSON format with date filters. Supports up to 50,000 records per request.

Query Parameters:

Policy Management

Policy is a JSON object containing all rule thresholds for a tenant. It is versioned automatically — every update increments the version number and stores a snapshot.

Get Current Policy

[TENANT] GET /v1/policy

Returns the active policy, its version number, and the date of last update.

curl -X GET https://froddy.io/v1/policy \
  -H "X-API-Key: your_key"

Response:

{
  "version": 5,
  "updated_at": "2026-02-20T14:30:00Z",
  "policy": {
    "R-COHORT": {
      "hold_usd": 25000,
      "block_usd": 100000
    },
    "R-CEIL": {
      "daily_ceiling_usd": 50000,
      "block_multiplier": 1.5
    },
    "R-VEL": {
      "window_hours": 1,
      "max_count": 20,
      "block_multiplier": 2
    },
    "R-DEDUP": {
      "max_entities": 3,
      "block_entities": 6,
      "window_hours": 24
    },
    "entity_overrides": {
      "partner_vip": {
        "R-CEIL": { "daily_ceiling_usd": 200000 },
        "R-COHORT": { "hold_usd": 50000, "block_usd": 300000 }
      }
    }
  }
}

Policy Schema — Rule Parameters

The entity_overrides object is optional. Keys are entity IDs; values are partial policy objects that override global thresholds for that specific entity.

Update Policy

[TENANT] PUT /v1/policy

Replaces the current policy. The version number auto-increments. A snapshot of the previous policy is stored in the history.

curl -X PUT https://froddy.io/v1/policy \
  -H "X-API-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "R-COHORT": { "hold_usd": 30000, "block_usd": 120000 },
    "R-CEIL": { "daily_ceiling_usd": 75000, "block_multiplier": 1.5 },
    "R-VEL": { "window_hours": 1, "max_count": 25, "block_multiplier": 2 },
    "R-DEDUP": { "max_entities": 3, "block_entities": 6, "window_hours": 24 }
  }'

Policy History

[TENANT] GET /v1/policy/history

Returns all previous policy versions with their snapshots.

curl -X GET https://froddy.io/v1/policy/history \
  -H "X-API-Key: your_key"

Policy Rollback

[TENANT] POST /v1/policy/rollback/{version}

Reverts the active policy to a specific historical version. This creates a new version (the version counter continues incrementing — it does not reset).

curl -X POST https://froddy.io/v1/policy/rollback/3 \
  -H "X-API-Key: your_key"

Rules

Get Active Rules

[TENANT] GET /v1/rules

Returns the set of active rules and their current parameters, derived from the active policy. If the policy changes, this endpoint reflects the new state immediately.

curl -X GET https://froddy.io/v1/rules \
  -H "X-API-Key: your_key"

Statistics

Aggregated statistics for the current tenant.

Aggregate Stats

[TENANT] GET /v1/stats

Returns aggregated counters: total evaluations, count by verdict, total amounts.

curl -X GET https://froddy.io/v1/stats \
  -H "X-API-Key: your_key"

Verdict Timeseries

[TENANT] GET /v1/stats/timeseries

Returns verdict counts over time (for charting purposes). Supports hourly and daily buckets.

curl -X GET "https://froddy.io/v1/stats/timeseries" \
  -H "X-API-Key: your_key"

Top Entities

[TENANT] GET /v1/stats/entities

Returns the top 20 entities ranked by the number of non-allow verdicts (hold + block triggers).

curl -X GET https://froddy.io/v1/stats/entities \
  -H "X-API-Key: your_key"

Alerting — Telegram (Optional)

RCL can send real-time alerts to a Telegram group or channel on every HOLD or BLOCK verdict. Note: Webhook and Email are the primary notification channels. Telegram is an optional additional channel that may be deprecated in favor of other messaging integrations.

Get Telegram Settings

[TENANT] GET /v1/telegram

Returns the current Telegram alert configuration for this tenant.

Configure Telegram

[TENANT] PUT /v1/telegram

curl -X PUT https://froddy.io/v1/telegram \
  -H "X-API-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_token": "123456:ABC-DEF...",
    "chat_id": "-1001234567890"
  }'

Remove Telegram Configuration

[TENANT] DELETE /v1/telegram

Disables Telegram alerts for this tenant.

Alert Format

Each alert includes: verdict emoji (🟡 hold / 🔴 block), rule name, entity ID, amount, human-readable reason, and timestamp.

🔴 RCL Alert: BLOCK

Entity: partner_42
Amount: $15,000.00
Rule: R-CEIL
Reason: daily ceiling exceeded: $53,000 / $50,000
Event: payout_12345
Time: 2026-02-20T14:30:01

Emoji mapping: 🔴 = block, 🟡 = hold-for-review.

Alerting — Webhook

RCL sends an HTTP POST request to a configured URL on every non-allow verdict.

Get Webhook Settings

[TENANT] GET /v1/webhook

Configure Webhook

[TENANT] PUT /v1/webhook

curl -X PUT https://froddy.io/v1/webhook \
  -H "X-API-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://your-system.com/rcl-alert"
  }'

Remove Webhook Configuration

[TENANT] DELETE /v1/webhook

For details on webhook delivery mechanics (payload format, retry policy, expected response), see Webhook Delivery.

Entity Overrides

Per-entity threshold overrides let you customize rule parameters for specific entities (e.g. VIP partners with legitimate high volumes) without changing the global policy.

Entity overrides can be managed both via the Policy API (entity_overrides field in the policy JSON) and via these dedicated endpoints.

Get Override

[TENANT] GET /v1/entity-overrides/{entity_id}

Returns the current threshold overrides for a specific entity.

Set Override

[TENANT] PUT /v1/entity-overrides/{entity_id}

curl -X PUT https://froddy.io/v1/entity-overrides/partner_vip \
  -H "X-API-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "R-CEIL": { "daily_ceiling_usd": 200000 },
    "R-COHORT": { "hold_usd": 50000, "block_usd": 300000 }
  }'

The override object is a partial policy — only include the rules and parameters you want to override.

Remove Override

[TENANT] DELETE /v1/entity-overrides/{entity_id}

Removes all custom thresholds for the entity. It will be evaluated against the global policy.

Sensitivity Analysis

Re-evaluate historical decisions using alternative thresholds, without affecting the live policy. Use this to model the impact of threshold changes before committing them.

[TENANT] POST /v1/sensitivity

Request body:

{
  "configs": [
    {
      "label": "conservative",
      "R-COHORT": { "hold_usd": 15000, "block_usd": 50000 },
      "R-CEIL": { "daily_ceiling_usd": 30000 },
      "R-VEL": {}
    },
    {
      "label": "permissive",
      "R-COHORT": { "hold_usd": 50000, "block_usd": 200000 }
    }
  ],
  "scenario": "default"
}

Accepts 1–5 configs. Each config can include R-COHORT, R-CEIL, R-VEL thresholds. The scenario filter is optional. Currently, only R-COHORT (single-transaction size) is re-evaluated against historical data. R-CEIL and R-VEL require full state replay and are not re-simulated. Historical data is loaded up to 50,000 decisions.

Response:

{
  "tenant": "demo",
  "total_decisions": 1500,
  "results": [
    {
      "label": "conservative",
      "config": { "R-COHORT": { "hold_usd": 15000, "block_usd": 50000 }, ... },
      "verdicts": { "allow": 1200, "hold": 250, "block": 50 },
      "hold_rate": 16.67,
      "block_rate": 3.33,
      "note": "Only R-COHORT is re-evaluated..."
    }
  ]
}

Pilot Report

Aggregated data suitable for generating a pilot summary report.

[TENANT] GET /v1/report

Optional query parameter: scenario (string). No date range filter — returns all data for the tenant.

Response:

{
  "tenant": "acme_corp",
  "scenario": "default",
  "policy": { "version": 5, "policy": {...}, "updated_at": "..." },
  "report": {
    "summary": { "total": 1500, "allow": 1200, "hold": 250, "block": 50 },
    "rule_breakdown": [...],
    "top_entities": [...],
    "daily_timeline": [...]
  },
  "generated_at": "2026-02-20T15:00:00"
}

The data is structured for programmatic consumption (PDF generation, dashboards). The report object contains aggregated data from db.get_report_data().

Health Check

[PUBLIC] GET /health

Returns the service and database health status. No authentication required.

curl https://froddy.io/health

{
  "status": "ok",
  "db_healthy": true,
  "fail_open": true,
  "service": "rcl-proto",
  "mode": "shadow",
  "version": "1.0.0",
  "db_backend": "SQLite",
  "uptime_s": 3600
}

status is "ok" when the database is healthy, "degraded" otherwise. fail_open indicates the service recommends clients proceed (allow) if RCL is unreachable.

Tenant Management (Admin)

These endpoints require the admin API key and are used for provisioning and managing tenants. They are not available to regular tenant API keys.

Note for external integrators: Tenant provisioning is handled by the Froddy team during pilot onboarding. These endpoints are documented here for completeness. You do not need to call them directly.

Create Tenant

[ADMIN] POST /v1/tenants

curl -X POST https://froddy.io/v1/tenants \
  -H "X-API-Key: admin_key" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "acme_corp",
    "name": "Acme Corporation"
  }'

Response:

{
  "tenant_slug": "acme_corp",
  "api_key": "rcl_abc123..."
}

List Tenants

[ADMIN] GET /v1/tenants

Delete Tenant

[ADMIN] DELETE /v1/tenants/{slug}

Idempotency

The /v1/evaluate endpoint is idempotent. If the same transaction is submitted more than once — identified by the combination of event_id + tenant + scenario — RCL returns the original verdict without re-evaluating.

This means:

• Retries due to network timeouts do not create duplicate decisions.
• The verdict is stable: submitting the same event_id a second time will not produce a different result, even if the policy has changed since the first evaluation.
• Each unique event_id is evaluated exactly once per tenant.

Recommended practice: Use your system's native payout identifier as event_id. This naturally ensures deduplication.

The idempotency scope is event_id + tenant + scenario. Decisions are stored indefinitely (no TTL) — an event_id that has been evaluated will always return the same verdict, even if the policy has changed since. The scenario field defaults to "default".

Error Handling

All errors return a JSON body with a detail field:

{
  "detail": "entity_id is required"
}

HTTP Status Codes

Timeouts & Latency

The /v1/evaluate endpoint is designed for synchronous, inline use in the payout execution path. Response times are typically in the low double-digit millisecond range.

Client-side recommendations:

• Set a reasonable timeout on your HTTP client (e.g. 500ms–2s depending on your requirements).
• Decide on a fallback behavior if RCL is unreachable. Most integrations default to allow to avoid blocking payouts during a service outage. This is a client-side decision.

Rate Limits

The /v1/evaluate endpoint is rate-limited per tenant.

No rate limit headers are currently returned. The limit applies to /v1/evaluate only; other endpoints are not rate-limited.

Versioning & Compatibility

The API is versioned via URL path prefix: all current endpoints are under /v1/.

• The current and only version is v1.
• Changes within v1 will be backward-compatible (additive fields, new endpoints).
• Breaking changes will be introduced under a new version prefix (e.g. /v2/).

Webhook Delivery

When a webhook URL is configured, RCL sends a POST request to that URL on every hold or block verdict.

Payload

The webhook receives a JSON POST with Content-Type: application/json:

{
  "event_id": "payout_12345",
  "entity_id": "partner_42",
  "amount": 15000.0,
  "verdict": "hold-for-review",
  "rule_id": "R-CEIL",
  "reason": "daily ceiling exceeded: $53,000 / $50,000",
  "evaluated_at": "2026-02-20T14:30:01"
}

The payload is identical for both webhook and Telegram alerts. Field rule_id (not rule) matches the evaluate response schema.

Delivery Expectations

• Delivery: Best-effort, fire-and-forget. Webhook is sent asynchronously in the background and does not block the /v1/evaluate response.
• Timeout: 5 seconds (httpx client timeout).
• Retries: None. Failed deliveries are not retried.
• Logging: HTTP 4xx/5xx responses and connection errors are logged server-side. They are not currently surfaced in the API or dashboard.
• HTTPS: Not strictly required — the URL must start with http:// or https://. HTTPS is strongly recommended for production.
• Expected receiver behavior: Any HTTP response is accepted. Non-2xx responses are logged as warnings but do not trigger retries.

Access Level Summary

Every endpoint falls into one of three access levels:

Full Endpoint Map

Froddy RCL API Reference · v1 · froddy.io · Product Docs · Interactive Demo