The Trinity Beast – API Reference

1. Authentication

All API requests require a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

2. LPO – Listener Price Oracle

The LPO delivers real-time cryptocurrency prices with sub-2ms cached responses. Prices are sourced from 6 persistent WebSocket feeds (Coinbase, Gemini, Kraken, Gate.io, Crypto.com, OKX) — 150 prewarmed assets pushed in real-time with zero REST polling. REST fallback (Gemini → Coinbase → Kraken) activates only if all WebSocket feeds for an asset are stale.

2.1 GET /price

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.cpmp-site.org/price?asset=btc"

2.2 POST /prices NEW

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"assets": ["BTC", "ETH", "SOL", "DOGE", "XRP"]}' \
  "https://api.cpmp-site.org/prices"

{
  "status": "✅ [LPO] [us-east-2] [BeastMain] [/prices] [200]",
  "status_code": 200,
  "endpoint": "/prices",
  "cluster_node": "BeastMain",
  "region": "us-east-2",
  "language": "en",
  "api_key_id": "ak_demo123",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbts/v1",
  "timestamp": "2026-05-28T20:32:08Z",
  "data": {
    "prices": {
      "BTC": {
        "exchange": "coinbase-ws",
        "cached": true,
        "cache_age_seconds": 0.082,
        "timestamp": 1780000328,
        "price": "73551.36"
      },
      "ETH": {
        "exchange": "coinbase-ws",
        "cached": true,
        "cache_age_seconds": 0.081,
        "timestamp": 1780000328,
        "price": "2016.48"
      },
      "SOL": {
        "exchange": "coinbase-ws",
        "cached": true,
        "cache_age_seconds": 0.217,
        "timestamp": 1780000328,
        "price": "82.36"
      },
      "DOGE": {
        "exchange": "coinbase-ws",
        "cached": true,
        "cache_age_seconds": 4.501,
        "timestamp": 1780000324,
        "price": "0.09983"
      },
      "XRP": {
        "exchange": "coinbase-ws",
        "cached": true,
        "cache_age_seconds": 1.389,
        "timestamp": 1780000327,
        "price": "1.3207"
      }
    },
    "asset_count": 5,
    "resolved_count": 5,
    "failed": [],
    "latency_ms": 0,
    "duration_ms": 12,
    "monthly_usage": 4521,
    "monthly_limit": 100000,
    "usage_pct": 4.52,
    "usage_warning": "",
    "usage_status": "✅"
  },
  "error": ""
}

{
  "status": "✅ [LPO] [us-east-2] [BeastMain] [/prices] [200]",
  ...
  "data": {
    "prices": {
      "BTC": { "exchange": "coinbase-ws", "cached": true, ... },
      "ETH": { "exchange": "coinbase-ws", "cached": true, ... }
    },
    "asset_count": 3,
    "resolved_count": 2,
    "failed": ["FAKECOIN"],
    ...
  }
}

{
  "status": "🛑 [LPO] [us-east-2] [BeastMain] [/prices] [400]",
  "status_code": 400,
  "endpoint": "/prices",
  "cluster_node": "BeastMain",
  "region": "us-east-2",
  "language": "en",
  "api_key_id": "ak_demo123",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbts/v1",
  "timestamp": "2026-05-28T20:32:23Z",
  "data": null,
  "error": "🛑 [LPO] [us-east-2] [BeastMain] [/prices] [400] Maximum 30 assets per request"
}

2.3 LPO Response Examples

Success Response (200 OK) — Cached Hit

{
  "status": "✅ [LPO] [us-east-2] [BeastMain] [/price] [200]",
  "status_code": 200,
  "endpoint": "/price",
  "cluster_node": "BeastMain",
  "region": "us-east-2",
  "language": "en",
  "api_key_id": "ak_demo123",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbts/v1",
  "timestamp": "2026-04-12T14:23:01Z",
  "data": {
    "usage_status": "✅",
    "api_key_id": "key_abc123",
    "asset": "BTC",
    "price": "83421.57",
    "source": "coinbase-ws",
    "timestamp": 1744466581,
    "readable_timestamp": "2026-04-12T14:23:01Z",
    "latency_ms": 0,
    "duration_ms": 0,
    "cached": true,
    "cache_duration_seconds": 4.2,
    "monthly_usage": 42,
    "monthly_limit": 1000,
    "usage_pct": 4.2,
    "usage_warning": "",
    "ip_address": "203.0.113.42"
  },
  "error": ""
}

Success Response (200 OK) — Live Fetch

{
  "status": "✅ [LPO] [us-east-2] [BeastMirror] [/price] [200]",
  "status_code": 200,
  "endpoint": "/price",
  "cluster_node": "BeastMirror",
  "region": "us-east-2",
  "language": "en",
  "api_key_id": "ak_demo123",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbts/v1",
  "timestamp": "2026-04-12T14:23:15Z",
  "data": {
    "usage_status": "✅",
    "api_key_id": "key_abc123",
    "asset": "ETH",
    "price": "3187.44",
    "source": "kraken",
    "timestamp": 1744466595,
    "readable_timestamp": "2026-04-12T14:23:15Z",
    "latency_ms": 38,
    "duration_ms": 38,
    "cached": false,
    "cache_duration_seconds": 0,
    "monthly_usage": 43,
    "monthly_limit": 1000,
    "usage_pct": 4.3,
    "usage_warning": "",
    "ip_address": "203.0.113.42"
  },
  "error": ""
}

Success Response — Graduated Usage Warnings

As monthly usage approaches the query limit, the data.usage_status field includes graduated warning indicators. Thresholds are runtime-tunable via application parameters.

🟡 Green Warning (≥85% of monthly limit)

{
  "status": "✅ [LPO] [us-east-2] [BeastMain] [/price] [200]",
  ...
  "data": {
    "usage_status": "✅🟡",
    ...
    "monthly_usage": 855,
    "monthly_limit": 1000,
    "usage_pct": 85.5,
    "usage_warning": "green",
    ...
  },
  "error": ""
}

⚠️ Yellow Warning (≥90% of monthly limit)

{
  "status": "✅ [LPO] [us-east-2] [BeastMain] [/price] [200]",
  ...
  "data": {
    "usage_status": "✅⚠️",
    ...
    "monthly_usage": 910,
    "monthly_limit": 1000,
    "usage_pct": 91.0,
    "usage_warning": "yellow",
    ...
  },
  "error": ""
}

🔴 Red Warning (≥95% of monthly limit)

{
  "status": "✅ [LPO] [us-east-2] [BeastMain] [/price] [200]",
  ...
  "data": {
    "usage_status": "✅🔴",
    ...
    "monthly_usage": 960,
    "monthly_limit": 1000,
    "usage_pct": 96.0,
    "usage_warning": "red",
    ...
  },
  "error": ""
}

Response Fields

The /price endpoint returns the standard 12-field UME envelope. Price data is nested inside the data field:

Envelope Fields (top level)

Price Data Fields (inside data)

3. LRS – Listener Report Service

The LRS provides access to your API usage history and aggregated statistics. Included with every subscription tier.

3.1 GET /reports/usage

# JSON (default)
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://lrs.cpmp-site.org/reports/usage?asset=BTC&page=1&page_size=50"

# CSV download
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://lrs.cpmp-site.org/reports/usage?format=csv" -o usage.csv

# Tab-delimited
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://lrs.cpmp-site.org/reports/usage?format=tsv" -o usage.tsv

# Plain text
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://lrs.cpmp-site.org/reports/usage?format=text"

3.2 GET /reports/summary

3.3 Output Formats

3.4 LRS Response Examples

Usage Report — JSON

{
  "logs": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "api_key_id": "key_abc123",
      "asset": "BTC",
      "price": 83421.57,
      "source": "coinbase",
      "cached": true,
      "latency_ms": 7,
      "duration_ms": 7,
      "ip_address": "203.0.113.42",
      "timestamp": 1744466581,
      "readable_timestamp": "2026-04-12T14:23:01Z",
      "cache_age_seconds": 4.2
    }
  ],
  "total_count": 1482,
  "page": 1,
  "page_size": 100,
  "filters": {
    "asset": "BTC"
  }
}

Usage Report — CSV

id,api_key_id,asset,price,source,cached,latency_ms,duration_ms,ip_address,timestamp,readable_timestamp,cache_age_seconds
a1b2c3d4-e5f6-7890-abcd-ef1234567890,key_abc123,BTC,83421.57000000,coinbase,true,7,7,203.0.113.42,1744466581,2026-04-12T14:23:01Z,4.200

Usage Report — Text

LRS Usage Report — Page 1 | Page Size 100 | Total Records 1482
================================================================================
[2026-04-12T14:23:01Z] a1b2c3d4... | Asset: BTC | Price: 83421.57000000 | Source: coinbase | Cached: true | Latency: 7ms | IP: 203.0.113.42

Summary Report — JSON

{
  "total_requests": 14820,
  "cache_hit_rate": 91.4,
  "avg_latency_ms": 9.3,
  "by_asset": {
    "BTC": 6210,
    "ETH": 4105,
    "SOL": 2380,
    "DOGE": 1240,
    "XRP": 885
  },
  "by_source": {
    "coinbase": 13540,
    "kraken": 1180,
    "gemini": 100
  },
  "date_range": {
    "start": "2026-03-13",
    "end": "2026-04-12"
  }
}

Summary Report — Text

LRS Summary Report — 2026-03-13 to 2026-04-12
============================================================
Total Requests  : 14820
Cache Hit Rate  : 91.40%
Avg Latency     : 9.30ms

By Asset:
  BTC        6210
  ETH        4105
  SOL        2380

By Source:
  coinbase     13540
  kraken       1180
  gemini       100

4. Supported Assets & Exchanges

The Trinity Beast LPO serves 150 prewarmed assets across 6 exchanges via persistent WebSocket connections. Each exchange maintains 25 unique assets with zero overlap — every asset is served by exactly one exchange. Prices arrive in real-time (push-based) before any request is made.

Exchange Overview

Assets by Exchange

Coinbase (25 assets)

BTC · ETH · SOL · DOGE · XRP · LINK · DOT · LTC · AVAX · UNI · PEPE · XLM · ETC · ICP · RENDER · BONK · BCH · JASMY · AXS · CHZ · STORJ · ZEC · DASH · CGLD · NEAR

Gemini (25 assets)

AAVE · ATOM · ARB · CRV · GRT · FIL · SHIB · BAT · LRC · MASK · ANKR · SKL · API3 · QNT · HYPE · LPT · HNT · UMA · JTO · CTX · POL · PNUT · POPCAT · DRIFT · CUBE

Kraken (25 assets)

NANO · SC · LSK · KAVA · BICO · RARI · OCEAN · CFG · CQT · ALGO · FET · FLOW · XTZ · QTUM · ICX · ASTR · ENJ · EGLD · COTI · MINA · GLMR · MOVR · KSM · TEER · CRO

Gate.io (25 assets)

BNB · TRX · APT · SEI · INJ · OP · SUI · VET · HBAR · SAND · MANA · S · CHR · FLR · THETA · CELR · REEF · DENT · HOT · POND · IOTX · ALICE · SUPER · FLUX · ONE

Crypto.com (25 assets)

TON · WLD · APE · BLUR · IMX · ENS · LDO · SNX · COMP · 1INCH · SUSHI · GALA · MAGIC · ORDI · PIXEL · RUNE · ARKM · DYM · GMX · CRO · TAO · AGLD · AR · AUDIO · POL

OKX (25 assets)

TIA · JUP · STRK · PYTH · W · ZRO · PENDLE · ONDO · WIF · FLOKI · NOT · AEVO · ENA · ETHFI · TURBO · NEIRO · DOGS · HMSTR · EIGEN · BOME · KAITO · GRASS · BANANA · ACE · TNSR

REST Fallback Sources (used only when WebSocket feeds are stale)

REST fallback is rarely triggered — with 6 WebSocket feeds pushing prices in real-time, the cache hit rate is 98.5%+. REST sources are only consulted when an asset's WebSocket price is older than the cache_ttl_seconds threshold (currently 300 seconds).

5. Error Codes & Response Convention

Status Indicators

Error Response Format

All error responses use the unified response envelope with color-coded bracket convention. The status field shows the indicator and origin metadata. The error field contains the full bracketed message.

{
  "status": "🛑 [LPO] [us-east-2] [BeastMain] [/price] [401]",
  "language": "en",
  "api_key_id": "ak_demo123",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbts/v1",
  "status_code": 401,
  "endpoint": "/price",
  "cluster_node": "BeastMain",
  "region": "us-east-2",
  "timestamp": "2026-04-26T16:20:03Z",
  "error": "🛑 [LPO] [us-east-2] [BeastMain] [/price] [401] Missing required API key parameter"
}

Rate Limit Warning (429)

{
  "status": "🛑 [LPO] [us-east-2] [BeastMirror] [/price] [429]",
  "language": "en",
  "api_key_id": "ak_demo123",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbts/v1",
  "error": "🛑 [LPO] [us-east-2] [BeastMirror] [429] ⚠️ Monthly query limit reached. You have used 1000 of 1000 allowed queries this month. Upgrade your plan for higher limits.",
  "code": 429,
  "region": "us-east-2",
  "cluster_node": "BeastMirror"
}

HTTP Status Codes

6. Rate Limits by Tier

7. Endpoint Summary

Public Endpoints

Admin Endpoints

Newsletter Admin Endpoints

Email Admin Endpoints

Support Admin Endpoints (X-Admin-Key)

Dashboard Customer Support Endpoints (Bearer Token)

Dashboard Admin Support Endpoints (Bearer Token + Admin Role)

Dashboard Admin Analytics Endpoints (Bearer Token + Admin Role)

8. UDP Protocol Access

Both LPO and LRS support UDP for low-latency, connectionless access. UDP is ideal for high-frequency price polling where occasional packet loss is acceptable.

# Python UDP example
import socket, json

sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
request = json.dumps({"api_key": "YOUR_API_KEY", "asset": "btc"}).encode()
sock.sendto(request, ("udp.cpmp-site.org", 2679))
data, addr = sock.recvfrom(4096)
print(json.loads(data))

# Python UDP example
import socket, json

sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
request = json.dumps({"api_key": "YOUR_API_KEY", "type": "summary"}).encode()
sock.sendto(request, ("udp.cpmp-site.org", 2680))
data, addr = sock.recvfrom(65535)
print(json.loads(data))

9. Network & Connectivity

Access Methods

PrivateLink Configuration

Enterprise subscribers can connect via AWS PrivateLink. Both LPO (TCP 8080) and LRS (TCP 9090) are available through the same PrivateLink endpoint. Create a VPC endpoint in your AWS account pointing to our PrivateLink service.

Data Sync

Usage logs are written to Aurora Serverless v2 by the LPO in real-time. A nightly sync job (1 AM EST) copies usage data from Aurora to ElastiCache for fast LRS report generation. Reports reflect data up to the previous day's sync.

10. Unified Response Envelope

Every HTTP endpoint in The Trinity Beast returns a consistent JSON envelope. This makes responses self-reporting — each response tells you which endpoint handled the request, which ECS container answered, and which AWS region served it.

Success Envelope

{
  "status": "✅ [LPO] [us-east-2] [BeastMain] [/health] [200]",
  "language": "en",
  "api_key_id": "ak_demo123",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbts/v1",
  "status_code": 200,
  "endpoint": "/health",
  "cluster_node": "BeastMain",
  "region": "us-east-2",
  "timestamp": "2026-04-26T16:20:03Z",
  "data": { "message": "Health Check - OK" }
}

Error Envelope

{
  "status": "🛑 [LPO] [us-east-2] [BeastMain] [/price] [401]",
  "language": "en",
  "api_key_id": "ak_demo123",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbts/v1",
  "status_code": 401,
  "endpoint": "/price",
  "cluster_node": "BeastMain",
  "region": "us-east-2",
  "timestamp": "2026-04-26T16:20:03Z",
  "error": "🛑 [LPO] [us-east-2] [BeastMain] [/price] [401] Missing required API key parameter"
}

Color-Coded Status Indicators

Every response uses a color-coded emoji indicator followed by bracketed origin metadata. This convention matches the usage logs, application logs, and subscriber-facing error messages — consistent across all messaging.

Bracket Convention

The bracket format self-reports the origin of every message at a glance:

INDICATOR [SERVICE] [REGION] [NODE] [ENDPOINT] [CODE] message

Example: 🛑 [LPO] [us-east-2] [BeastMirror] [/admin/config] [403] Invalid admin key

This convention is used consistently across:

• HTTP response status field (unified envelope)
• HTTP response error field (error messages)
• Subscriber-facing price errors (StandardErrorResponse)
• Application logs (structured console output)
• Usage logs (Aurora usage_logs table)

Envelope Fields

Diagram 10.1 — Request Flow & Response Envelope

flowchart LR
    A["Client Request"] --> B["⚖️ ALB / NLB"]
    B --> C{"ECS Container"}
    C --> D["BeastMain"]
    C --> E["BeastMirror"]
    C --> F["BeastLRS"]
    D --> G["WriteJSON / WriteError"]
    E --> G
    F --> G
    G --> H["Unified Envelope"]
    H --> I["status: ok | error"]
    H --> J["endpoint: /path"]
    H --> K["cluster_node: BeastX"]
    H --> L["region: us-east-2"]
    H --> M["timestamp: RFC3339"]
    H --> N["data / error payload"]

    style A fill:#334155,stroke:#475569,color:#cbd5e1
    style B fill:#334155,stroke:#475569,color:#cbd5e1
    style C fill:#2d4a5e,stroke:#475569,color:#cbd5e1
    style D fill:#2d4a5e,stroke:#475569,color:#cbd5e1
    style E fill:#2d4a5e,stroke:#475569,color:#cbd5e1
    style F fill:#2d4a5e,stroke:#475569,color:#cbd5e1
    style G fill:#3d3455,stroke:#475569,color:#cbd5e1
    style H fill:#FF9900,stroke:#cc7a00,color:#0f172a
    style I fill:#1e293b,stroke:#475569,color:#94a3b8
    style J fill:#1e293b,stroke:#475569,color:#94a3b8
    style K fill:#1e293b,stroke:#475569,color:#94a3b8
    style L fill:#1e293b,stroke:#475569,color:#94a3b8
    style M fill:#1e293b,stroke:#475569,color:#94a3b8
    style N fill:#1e293b,stroke:#475569,color:#94a3b8
        

11. Complete Endpoint Inventory

Comprehensive inventory of every registered route across The Trinity Beast services.

12. Public Infrastructure Endpoints

These endpoints expose operational metrics for the public Infrastructure Live page. No authentication required. Safe for public consumption — sensitive internals (DB pools, internal IPs, config) are stripped.

curl https://api.cpmp-site.org/public/status

curl https://api.cpmp-site.org/public/cluster

{
  "status": "ok",
  "nodes_found": 4,
  "nodes_expected": 4,
  "region": "us-east-2",
  "nodes": [
    {
      "name": "BeastMain",
      "role": "LPO + LRS",
      "uptime_seconds": 86412.3,
      "tcp_requests": 1247,
      "udp_requests": 0,
      "lrs_requests": 83,
      "syncmap_hit_pct": 99.2,
      "cache_hit_pct": 99.8,
      "errors_5xx": 0,
      "errors_4xx": 12,
      "rate_limit_hits": 0
    }
  ],
  "aggregated": {
    "tcp_requests": 3891,
    "udp_requests": 0,
    "lrs_requests": 249,
    "syncmap_hit_pct": 99.1,
    "cache_hit_pct": 99.7,
    "rate_limit_hits": 0,
    "errors_5xx": 0,
    "errors_4xx": 34,
    "bg_work_dropped": 0
  }
}

curl https://api.cpmp-site.org/public/infrastructure

{
  "status": "✅ [LPO] [us-east-2] [BeastMain] [/public/infrastructure] [200]",
  "status_code": 200,
  "endpoint": "/public/infrastructure",
  "cluster_node": "BeastMain",
  "region": "us-east-2",
  "language": "en",
  "api_key_id": "",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbi/v1",
  "timestamp": "2026-05-30T17:00:00Z",
  "data": {
    "cloudfront": { "requests_24h": 1095, "bytes_24h": 17114513, "bytes_human": "16 MB" },
    "waf": { "alb_blocked_24h": 1186, "alb_allowed_24h": 3302, "cf_blocked_24h": 0 },
    "sqs": { "visible": 0, "in_flight": 0 },
    "lambda": {
      "receipt": { "state": "Active", "last_deployed": "", "invocations_24h": 0, "errors_24h": 0 },
      "writer": { "state": "Active", "last_deployed": "", "invocations_24h": 141, "errors_24h": 0 }
    },
    "sync": {
      "last_run": "May 30 01:00AM",
      "status": "success",
      "duration": "783.351423ms",
      "new_logs": "154 new logs loaded",
      "search_index": { "languages": 12, "sections": 3150 }
    },
    "guardduty": { "active_findings": 0, "status": "active" },
    "alarms": { "total": 17, "ok": 16, "alarm": 1, "insufficient_data": 0 },
    "honeypot": { "active": true, "endpoints": 12, "total_hits": 22, "auto_blocked": 77, "pending_queue": 0 },
    "autoops": {
      "active": true,
      "lambdas": {
        "notify_invocations_24h": 14,
        "self_heal_invocations_24h": 61,
        "waf_action_invocations_24h": 3,
        "honeypot_processor_invocations_24h": 288,
        "bedrock_analyze_invocations_24h": 288,
        "raima_support_invocations_24h": 11,
        "digest_invocations_24h": 1,
        "total_invocations_24h": 666,
        "total_errors_24h": 0
      },
      "step_functions": { "executions_24h": 62, "succeeded_24h": 62, "failed_24h": 0 },
      "eventbridge": {
        "rules": [
          { "name": "tbi-ops-alarm-trigger", "schedule": "", "pattern": "CloudWatch alarm → ALARM", "target": "Step Function: health-check-heal" },
          { "name": "tbi-ops-honeypot-queue-processor", "schedule": "rate(5 minutes)", "pattern": "", "target": "Lambda: honeypot-processor" }
        ],
        "total": 6
      },
      "waf_blocked_by_ops": 0,
      "self_heal_count": 0,
      "last_threat": "LOW"
    },
    "cache": {
      "engine": "valkey",
      "version": "7.2.6",
      "items": 38675,
      "hit_rate": 65.7,
      "memory_used": "1.42G",
      "memory_percent": 0.0,
      "cpu_percent": 3.0
    },
    "services": {
      "cluster": "trinity-beast-fargate-cluster",
      "total_desired": 4,
      "total_running": 4,
      "total_pending": 0,
      "all_healthy": true,
      "services": [
        { "name": "trinity-beast-main-service", "status": "ACTIVE", "desired": 1, "running": 1, "pending": 0, "healthy": true, "task_family": "trinity-beast-main-task" }
      ]
    },
    "translation": {
      "active": true,
      "daily_spend_usd": 0,
      "daily_limit_usd": 600,
      "active_jobs": 0,
      "queue_depth": 0,
      "cost_per_pair_usd": 1.65,
      "daily_input_tokens": 0,
      "daily_output_tokens": 0,
      "daily_token_limit": 50000000
    }
  },
  "error": ""
}

13. Admin Endpoints — Full Reference

All admin endpoints require the X-Admin-Key header. The admin key is established via the one-time /admin/bootstrap-key endpoint on first deployment.

X-Admin-Key: YOUR_ADMIN_KEY

System Management

Endpoints for managing application configuration, demo mode, system profiles, and parameter reloading.

Metrics & Monitoring

Real-time observability into The Trinity Beast runtime performance, price feed health, and adaptive governor behavior.

Exchange Management

Full CRUD for exchange feed configurations and asset symbol mappings. Changes take effect immediately — no restart required.

Database & Cache

Direct database and cache access for administrative operations. These endpoints execute commands against Aurora Serverless v2 and ElastiCache.

{
  "query": "SELECT COUNT(*) AS count FROM usage_logs WHERE asset = $1",
  "args": ["BTC"],
  "mode": "read"
}

Support Ticket Administration

Partner Administration

Newsletter Administration

Full newsletter lifecycle management — templates, composition, subscriber management, and sending via SES.

Email Administration

Direct email composition and sending — templates, verified senders, draft management, and delivery via SES.

Email Testing

Diagnostic endpoints for verifying email rendering without triggering real payment processing or translation jobs.

POST /admin/test-refund-email

{
  "email": "recipient@example.com",
  "lang": "ur",
  "type": "translation"
}

{
  "status": "sent",
  "email": "recipient@example.com",
  "lang": "ur",
  "type": "translation",
  "subject": "رقم کی واپسی کی تصدیق — Trinity-Beast-API-Reference.html"
}

POST /admin/test-finalize-email

Sends a mock translation completion email with realistic dummy data. The email includes the full stats bar (documents, languages, succeeded/failed counts, duration, cost/fee/total, state badge) and the Cost by Language table showing per-language Bedrock token usage and cost. Subject line is prefixed with [TEST] and a purple banner at the top makes it immediately clear this is not a real alert.

{
  "email": "recipient@example.com",
  "scenario": "succeeded"
}

// scenario values:
// "succeeded" — 2 docs × 11 langs, all 22 pairs succeeded, full cost breakdown table
// "partial"   — 2 docs × 11 langs, 16/22 pairs succeeded, 3 failed pairs listed, partial cost table
// "failed"    — 1 doc × 3 langs, all failed, no cost table, CRITICAL badge

{
  "status": "sent",
  "email": "recipient@example.com",
  "scenario": "partial",
  "subject": "[TEST] Translation Complete: 2 docs × 11 langs — 16/22 pairs PARTIAL"
}

13b. Translation Engine Admin Endpoints

Internal admin endpoints for the document translation pipeline. All require the X-Admin-Key header. Full documentation: AutoOps Translation Engine.

Job Submission

Monitoring

Control

Cost Protection — 429 Responses

The submit handler enforces two independent daily caps. Either can trigger a 429:

Emergency kill switch: SET autoops:bedrock:kill 1 in Valkey — halts all translation operations immediately.

14. Dashboard Support Endpoints — Full Reference

The dashboard exposes 8 support endpoints split into two groups: Customer (authenticated via Bearer token, scoped to the user's own tickets) and Admin (Bearer token + admin role, system-wide access). All responses use the standard 12-field UME envelope.

Customer Endpoints (Bearer Token)

These endpoints are scoped to the authenticated user's email. Customers can only see and interact with their own tickets. Internal admin notes are never exposed.

GET /dashboard/api/support/tickets

List the authenticated user's support tickets, ordered by most recent. Limited to 50.

Authentication: Bearer token (session cookie)

{
  "status": "✅ [LPO] [us-east-2] [BeastMain] [/dashboard/api/support/tickets] [200]",
  "status_code": 200,
  "endpoint": "/dashboard/api/support/tickets",
  "cluster_node": "BeastMain",
  "region": "us-east-2",
  "language": "en",
  "api_key_id": "ak_demo123",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbi-dashboard/v1",
  "timestamp": "2026-05-17T19:00:00Z",
  "data": {
    "tickets": [
      {
        "ticket_number": "TKT-20260517-A3F2",
        "subject": "API key not working after renewal",
        "status": "open",
        "created_at": "2026-05-17T14:30:00Z"
      }
    ]
  },
  "error": ""
}

GET /dashboard/api/support/tickets/{ticket_number}

Full ticket detail with reply thread. Excludes internal admin notes. Shows translated replies in the customer's language.

Authentication: Bearer token (session cookie). Must own the ticket.

{
  "status": "✅ [LPO] [us-east-2] [BeastMain] [/dashboard/api/support/tickets/TKT-20260517-A3F2] [200]",
  "status_code": 200,
  "endpoint": "/dashboard/api/support/tickets/TKT-20260517-A3F2",
  "cluster_node": "BeastMain",
  "region": "us-east-2",
  "language": "en",
  "api_key_id": "ak_demo123",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbi-dashboard/v1",
  "timestamp": "2026-05-17T19:00:00Z",
  "data": {
    "ticket": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "ticket_number": "TKT-20260517-A3F2",
      "name": "Jane Developer",
      "category": "technical",
      "subject": "API key not working after renewal",
      "message": "I renewed my subscription yesterday but my API key returns 403...",
      "status": "open",
      "preferred_lang": "en",
      "created_at": "2026-05-17T14:30:00Z",
      "updated_at": "2026-05-17T15:45:00Z"
    },
    "replies": [
      {
        "id": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
        "author_type": "admin",
        "message": "I've checked your key — it looks like the cache hadn't refreshed yet. Should be working now.",
        "created_at": "2026-05-17T15:45:00Z"
      }
    ]
  },
  "error": ""
}

POST /dashboard/api/support/tickets/{ticket_number}/reply

Post a customer reply. Max 10,000 characters. Auto-translates to English for admin readability. Notifies admin via email. Re-opens tickets in awaiting_customer or resolved state.

Authentication: Bearer token (session cookie). Must own the ticket.

Request body:

{
  "message": "Thanks, it's working now! One more question — can I add more assets to my plan?"
}

Response:

{
  "status": "✅ [LPO] [us-east-2] [BeastMain] [/dashboard/api/support/tickets/TKT-20260517-A3F2/reply] [200]",
  "status_code": 200,
  "endpoint": "/dashboard/api/support/tickets/TKT-20260517-A3F2/reply",
  "cluster_node": "BeastMain",
  "region": "us-east-2",
  "language": "en",
  "api_key_id": "ak_demo123",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbi-dashboard/v1",
  "timestamp": "2026-05-17T19:10:00Z",
  "data": {
    "reply_id": "c4d5e6f7-a8b9-0123-4567-890abcdef123",
    "message": "Reply posted"
  },
  "error": ""
}

Errors: 400 if message is empty or exceeds 10,000 chars. 400 if ticket is closed. 404 if ticket not found or not owned by user.

POST /dashboard/api/support/tickets/{ticket_number}/resolve

Mark own ticket as resolved. Notifies admin. Closed tickets cannot be resolved (already terminal). Idempotent — resolving an already-resolved ticket returns success.

Authentication: Bearer token (session cookie). Must own the ticket.

Request body: Empty {}

Response:

{
  "status": "✅ [LPO] [us-east-2] [BeastMain] [/dashboard/api/support/tickets/TKT-20260517-A3F2/resolve] [200]",
  "status_code": 200,
  "endpoint": "/dashboard/api/support/tickets/TKT-20260517-A3F2/resolve",
  "cluster_node": "BeastMain",
  "region": "us-east-2",
  "language": "en",
  "api_key_id": "ak_demo123",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbi-dashboard/v1",
  "timestamp": "2026-05-17T19:15:00Z",
  "data": {
    "message": "Ticket marked resolved",
    "status": "resolved"
  },
  "error": ""
}

Admin Endpoints (Bearer Token + Admin Role)

System-wide ticket management. Admin can see all tickets, all replies (including internal notes), customer IPs, and full audit trail. Requires admin role on the session.

GET /dashboard/api/admin/support/tickets

List all tickets system-wide. Supports filtering by status and category. Limited to 200 results, ordered by created_at DESC.

Authentication: Bearer token + admin role

Query parameters:

{
  "status": "✅ [LPO] [us-east-2] [BeastMain] [/dashboard/api/admin/support/tickets] [200]",
  "status_code": 200,
  "endpoint": "/dashboard/api/admin/support/tickets",
  "cluster_node": "BeastMain",
  "region": "us-east-2",
  "language": "en",
  "api_key_id": "ak_demo123",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbi-dashboard/v1",
  "timestamp": "2026-05-17T19:00:00Z",
  "data": {
    "tickets": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "ticket_number": "TKT-20260517-A3F2",
        "name": "Jane Developer",
        "email": "jane@example.com",
        "category": "technical",
        "subject": "API key not working after renewal",
        "status": "open",
        "created_at": "2026-05-17T14:30:00Z",
        "updated_at": "2026-05-17T15:45:00Z"
      }
    ]
  },
  "error": ""
}

GET /dashboard/api/admin/support/tickets/{id}

Full ticket detail by UUID. Includes all replies (internal notes visible), customer IP, email, preferred language, and English translation of the original message.

Authentication: Bearer token + admin role

{
  "status": "✅ [LPO] [us-east-2] [BeastMain] [/dashboard/api/admin/support/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890] [200]",
  "status_code": 200,
  "endpoint": "/dashboard/api/admin/support/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "cluster_node": "BeastMain",
  "region": "us-east-2",
  "language": "en",
  "api_key_id": "ak_demo123",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbi-dashboard/v1",
  "timestamp": "2026-05-17T19:00:00Z",
  "data": {
    "ticket": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "ticket_number": "TKT-20260517-A3F2",
      "name": "Jane Developer",
      "email": "jane@example.com",
      "category": "technical",
      "subject": "API key not working after renewal",
      "message": "I renewed my subscription yesterday but my API key returns 403...",
      "message_en": "I renewed my subscription yesterday but my API key returns 403...",
      "preferred_lang": "en",
      "status": "open",
      "client_ip": "203.0.113.50",
      "created_at": "2026-05-17T14:30:00Z",
      "updated_at": "2026-05-17T15:45:00Z"
    },
    "replies": [
      {
        "id": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
        "author": "CoryDeanKalani@CPMP-Site.org",
        "author_type": "admin",
        "message": "I've checked your key — it looks like the cache hadn't refreshed yet. Should be working now.",
        "is_internal": false,
        "created_at": "2026-05-17T15:45:00Z"
      },
      {
        "id": "d5e6f7a8-b9c0-1234-5678-90abcdef1234",
        "author": "CoryDeanKalani@CPMP-Site.org",
        "author_type": "admin",
        "message": "Note: key cache was stale due to recent deploy. Forced invalidation.",
        "is_internal": true,
        "created_at": "2026-05-17T15:44:00Z"
      }
    ]
  },
  "error": ""
}

POST /dashboard/api/admin/support/tickets/{id}/reply

Post an admin reply. Auto-translates to customer's language and emails them. Includes a one-click resolve link in the email (single-use, 30-day TTL). Internal notes (is_internal: true) are never shown to the customer or emailed. First reply auto-advances status from new to open.

Authentication: Bearer token + admin role

Request body:

{
  "message": "I've checked your key — it looks like the cache hadn't refreshed yet. Should be working now.",
  "is_internal": false
}

Response:

{
  "status": "✅ [LPO] [us-east-2] [BeastMain] [/dashboard/api/admin/support/tickets/a1b2c3d4/reply] [200]",
  "status_code": 200,
  "endpoint": "/dashboard/api/admin/support/tickets/a1b2c3d4/reply",
  "cluster_node": "BeastMain",
  "region": "us-east-2",
  "language": "en",
  "api_key_id": "ak_demo123",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbi-dashboard/v1",
  "timestamp": "2026-05-17T19:10:00Z",
  "data": {
    "reply_id": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
    "message": "Reply posted"
  },
  "error": ""
}

Errors: 400 if message is empty. 404 if ticket not found.

POST /dashboard/api/admin/support/tickets/{id}/status

Update a ticket's status. Audit-logged with the admin's email. Valid statuses: new, open, in_progress, awaiting_customer, resolved, closed.

Authentication: Bearer token + admin role

Request body:

{
  "status": "in_progress"
}

Response:

{
  "status": "✅ [LPO] [us-east-2] [BeastMain] [/dashboard/api/admin/support/tickets/a1b2c3d4/status] [200]",
  "status_code": 200,
  "endpoint": "/dashboard/api/admin/support/tickets/a1b2c3d4/status",
  "cluster_node": "BeastMain",
  "region": "us-east-2",
  "language": "en",
  "api_key_id": "ak_demo123",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbi-dashboard/v1",
  "timestamp": "2026-05-17T19:12:00Z",
  "data": {
    "message": "Status updated",
    "status": "in_progress"
  },
  "error": ""
}

Errors: 400 if status is invalid. 404 if ticket not found.

Ticket Status Flow

Tickets follow a lifecycle with automatic transitions:

Note: Closed tickets cannot be replied to by customers. They must open a new ticket.

GET /dashboard/api/admin/daily-rollup

Returns per-day usage aggregates served from the mv_usage_daily materialized view in Aurora. Because the data is precomputed, this endpoint is fast and never scans the full usage_logs table. The view is refreshed every 5 minutes by the pg_cron job tbi-mv-usage-daily-refresh running natively inside Aurora; the last_refreshed field tells consumers how current the data is.

Authentication: Bearer token + admin role

Response:

{
  "status": "✅ [LPO] [us-east-2] [BeastMain] [/dashboard/api/admin/daily-rollup] [200]",
  "status_code": 200,
  "endpoint": "/dashboard/api/admin/daily-rollup",
  "cluster_node": "BeastMain",
  "region": "us-east-2",
  "language": "en",
  "api_key_id": "ak_demo123",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbi-dashboard/v1",
  "timestamp": "2026-05-30T23:30:00Z",
  "data": {
    "days": [
      {
        "day": "2026-05-30",
        "total_requests": 4821,
        "avg_latency_ms": 12.4,
        "p50_latency_ms": 9,
        "p95_latency_ms": 38,
        "p99_latency_ms": 71,
        "cached_requests": 4603,
        "cache_hit_rate_pct": 95.48,
        "distinct_assets": 142,
        "distinct_api_keys": 6,
        "distinct_sources": 6,
        "distinct_nodes": 3
      }
    ],
    "count": 1,
    "last_refreshed": "2026-05-30T23:26:00Z"
  },
  "error": ""
}

Notes: days is always an array (empty [] when no data, never null). last_refreshed reflects the most recent materialized-view refresh, not the request time.

15. Translation Service API

AI-powered document translation with sentinel preprocessing and multi-layer validation. Translates technical documentation while preserving code blocks, Mermaid diagrams, brand terms, and all technical identifiers. Choose from three AI agents based on your needs.

15.1 GET /translate/models

Returns the available AI agents with token-based pricing information. Public — no authentication required.

Response

{
  "status_code": 200,
  "data": {
    "models": [
      {
        "id": "claude-haiku-3.5",
        "name": "Claude Haiku 3.5",
        "tier": "Good",
        "input_rate_per_1m": 1.0,
        "output_rate_per_1m": 5.0,
        "estimated_cost_per_pair": 0.03,
        "speed": "fast",
        "quality": "good",
        "description": "Fast and affordable. Best for Latin-script languages and straightforward documents."
      },
      {
        "id": "claude-sonnet-4.6",
        "name": "Claude Sonnet 4.6",
        "tier": "Better",
        "input_rate_per_1m": 3.0,
        "output_rate_per_1m": 15.0,
        "estimated_cost_per_pair": 0.08,
        "speed": "moderate",
        "quality": "excellent",
        "description": "Balanced speed and quality. Handles complex scripts and technical documents well. Default choice."
      },
      {
        "id": "claude-opus-4",
        "name": "Claude Opus 4",
        "tier": "Best",
        "input_rate_per_1m": 5.0,
        "output_rate_per_1m": 25.0,
        "estimated_cost_per_pair": 0.05,
        "speed": "slow",
        "quality": "exceptional",
        "description": "Highest quality translations. Best for critical documents and complex grammar."
      }
    ],
    "default": "claude-sonnet-4.6",
    "pricing_note": "Rates are per 1M tokens. estimated_cost_per_pair is for a typical 50KB document (one language). Actual cost depends on document size and content density."
  }
}

15.2 POST /translate/quote

Submit a document URL and target languages to receive an instant price quote. The engine fetches and analyzes your document (size, chunks, code blocks, diagrams) and returns a detailed cost breakdown.

Request Body

{
  "doc_url": "https://your-site.com/docs/api-reference.html",
  "langs": ["es", "fr", "de", "ja", "zh"],
  "model": "claude-sonnet-4.6"
}

Response (200 OK)

{
  "status_code": 200,
  "data": {
    "quote_id": "qt-a1b2c3d4e5f6",
    "doc_name": "api-reference.html",
    "languages": ["es", "fr", "de", "ja", "zh"],
    "model": "claude-sonnet-4.6",
    "analysis": {
      "size_bytes": 63488,
      "estimated_chunks": 4,
      "difficulty": "moderate",
      "code_blocks": 12,
      "diagrams": 2
    },
    "pricing": {
      "estimated_input_tokens": 21700,
      "estimated_output_tokens": 16492,
      "input_rate_per_1m": 3.0,
      "output_rate_per_1m": 15.0,
      "cost_per_pair": 0.31,
      "pairs": 5,
      "subtotal": 1.57,
      "markup_pct": 30,
      "total_price": 2.04,
      "per_language": [
        {
          "lang": "es",
          "model": "claude-haiku-3.5",
          "estimated_input_tokens": 21700,
          "estimated_output_tokens": 16492,
          "bedrock_cost": 0.05,
          "infra_cost": 0.14,
          "pair_subtotal": 0.19,
          "pair_with_markup": 0.24
        },
        {
          "lang": "ja",
          "model": "claude-sonnet-4.6",
          "estimated_input_tokens": 21700,
          "estimated_output_tokens": 16492,
          "bedrock_cost": 0.31,
          "infra_cost": 0.14,
          "pair_subtotal": 0.45,
          "pair_with_markup": 0.59
        }
      ]
    },
    "expires_at": "2026-05-23T15:00:00Z",
    "accept_url": "/translate/accept/qt-a1b2c3d4e5f6"
  }
}

15.3 GET /translate/quote/{quote_id}

Retrieve the details of an existing quote, including its current state (pending, accepted, expired).

Response (200 OK)

{
  "status_code": 200,
  "data": {
    "quote_id": "qt-a1b2c3d4e5f6",
    "doc_url": "https://your-site.com/docs/api-reference.html",
    "doc_name": "api-reference.html",
    "languages": ["es", "fr", "de", "ja", "zh"],
    "model": "claude-sonnet-4.6",
    "analysis": {
      "size_bytes": 63488,
      "estimated_chunks": 4,
      "difficulty": "moderate",
      "code_blocks": 12,
      "diagrams": 2
    },
    "pricing": {
      "estimated_input_tokens": 21700,
      "estimated_output_tokens": 16492,
      "input_rate_per_1m": 3.0,
      "output_rate_per_1m": 15.0,
      "cost_per_pair": 0.31,
      "pairs": 5,
      "subtotal": 1.57,
      "markup_pct": 30,
      "total_price": 2.04
    },
    "state": "pending",
    "expires_at": "2026-05-23T15:00:00Z",
    "accepted_at": "",
    "job_id": ""
  }
}

15.4 GET /translate/quotes

List all quotes for the authenticated API key, ordered by most recent. Limited to 30.

Response (200 OK)

{
  "status_code": 200,
  "data": {
    "quotes": [
      {
        "quote_id": "qt-a1b2c3d4e5f6",
        "doc_name": "api-reference.html",
        "lang_count": 5,
        "total_price": 11.05,
        "model": "claude-sonnet-4.6",
        "state": "accepted",
        "expires_at": "2026-05-23T15:00:00Z",
        "job_id": "019e4b8a37bc-abc123"
      },
      {
        "quote_id": "qt-f6e5d4c3b2a1",
        "doc_name": "architecture-guide.html",
        "lang_count": 3,
        "total_price": 6.45,
        "model": "claude-haiku-3.5",
        "state": "pending",
        "expires_at": "2026-05-23T18:00:00Z",
        "job_id": ""
      }
    ],
    "count": 2
  }
}

15.5 POST /translate/accept/{quote_id}

Accept a pending quote and begin translation. Your payment method on file is charged the quoted amount. Translation starts immediately upon acceptance.

Response (200 OK)

{
  "status_code": 200,
  "data": {
    "job_id": "019e4b8a37bc-abc123",
    "state": "queued",
    "quote_id": "qt-a1b2c3d4e5f6",
    "model": "claude-sonnet-4.6",
    "total_price": 11.05,
    "pairs": 5,
    "message": "Translation job started. You will receive an email when complete."
  }
}

Error Responses

15.6 POST /translate/accept-batch

Accept multiple pending quotes in a single transaction. A single Stripe PaymentIntent is created for the batch total. Each quote becomes a separate translation job. Maximum 6 quotes per batch.

Request Body

{
  "quote_ids": [
    "qt-a1b2c3d4e5f6",
    "qt-b2c3d4e5f6a7",
    "qt-c3d4e5f6a7b8"
  ]
}

Parameters

Response (200 OK)

{
  "status_code": 200,
  "data": {
    "batch_total": 33.15,
    "jobs": [
      {
        "job_id": "019e4b8a37bc-abc123",
        "quote_id": "qt-a1b2c3d4e5f6",
        "state": "queued",
        "pairs": 5,
        "price": 11.05
      },
      {
        "job_id": "019e4b8a37bc-def456",
        "quote_id": "qt-b2c3d4e5f6a7",
        "state": "queued",
        "pairs": 3,
        "price": 8.40
      },
      {
        "job_id": "019e4b8a37bc-ghi789",
        "quote_id": "qt-c3d4e5f6a7b8",
        "state": "queued",
        "pairs": 6,
        "price": 13.70
      }
    ],
    "payment_intent_id": "pi_3abc123def456",
    "message": "3 translation jobs started. You will receive an email when each completes."
  }
}

Error Responses

15.7 Supported Languages

35 validated languages with production-tested sentinel configurations. Any additional language Claude supports can be requested.

15.8 POST /admin/translate/refund/{quote_id}

Issues a full or partial refund for a completed translation purchase. Admin-only — requires X-Admin-Key header. Refunds are processed via Stripe and the customer receives a confirmation email automatically.

Path Parameters

Request Body (Optional)

POST /admin/translate/refund/qt-a1b2c3d4e5f6
X-Admin-Key: your-admin-key
Content-Type: application/json

{
  "amount": 5.00,
  "reason": "Customer unsatisfied with Japanese translation quality"
}

Response (200 OK)

{
  "status": "✅ [LPO] [us-east-2] [BeastMain] [/admin/translate/refund/qt-a1b2c3d4e5f6] [200]",
  "status_code": 200,
  "data": {
    "status": "refunded",
    "quote_id": "qt-a1b2c3d4e5f6",
    "refund_id": "re_1234567890",
    "refund_amount": 10.75,
    "original_amount": 10.75,
    "partial": false,
    "stripe_status": "succeeded"
  },
  "error": ""
}

15.8 Brand Terms Protection

Customers can configure up to 150 brand terms that are automatically protected during every translation job. These terms are never translated or transliterated — they appear exactly as written in every target language. Terms are managed via the dashboard API and apply to all future translation jobs for the account.

GET /dashboard/api/protected-terms

Returns the customer's current list of protected brand terms. Requires dashboard Bearer token authentication.

Response (200 OK)

{
  "status_code": 200,
  "data": {
    "terms": ["Acme Corp", "DataForge", "CloudSync API", "John Smith"],
    "count": 4,
    "limit": 150
  },
  "error": ""
}

PUT /dashboard/api/protected-terms

Replaces the customer's entire brand terms list. Requires dashboard Bearer token authentication.

Request Body

PUT /dashboard/api/protected-terms
Authorization: Bearer your-session-token
Content-Type: application/json

{
  "terms": ["Acme Corp", "DataForge", "CloudSync API", "John Smith", "SyncEngine"]
}

Response (200 OK)

{
  "status_code": 200,
  "data": {
    "message": "Saved 5 brand terms",
    "terms": ["Acme Corp", "DataForge", "CloudSync API", "John Smith", "SyncEngine"],
    "count": 5,
    "limit": 150
  },
  "error": ""
}

15.9 Dashboard Translation Endpoints

Authenticated dashboard endpoints for translation spend tracking, refund history, and job completion notifications. All require Bearer token authentication via the dashboard session.

GET /dashboard/api/translate/spend

Returns translation spend aggregated by month and model for the last 6 months. Customers see only their own spend; admins see all accounts.

Response (200 OK)

{
  "status_code": 200,
  "data": {
    "summary": {
      "total_revenue_usd": 247.50,
      "total_bedrock_cost_usd": 89.30,
      "total_jobs": 18,
      "total_pairs": 142
    },
    "months": [
      {
        "month": "2026-05",
        "revenue_usd": 132.00,
        "bedrock_cost_usd": 48.20,
        "jobs": 10,
        "pairs": 78,
        "by_model": {
          "claude-haiku-3.5": {"jobs": 3, "pairs": 24, "cost_usd": 9.60},
          "claude-sonnet-4.6": {"jobs": 6, "pairs": 48, "cost_usd": 79.20},
          "claude-opus-4": {"jobs": 1, "pairs": 6, "cost_usd": 43.20}
        }
      }
    ]
  },
  "error": ""
}

GET /dashboard/api/translate/refunds

Returns refund history for translation purchases. Admin-only — non-admin accounts receive 403.

Response (200 OK)

{
  "status_code": 200,
  "data": {
    "refunds": [
      {
        "refunded_at": "2026-05-22T14:30:00Z",
        "quote_id": "qt-a1b2c3d4e5f6",
        "doc_name": "api-reference.html",
        "customer_email": "user@example.com",
        "original_amount": 11.05,
        "refund_amount": 11.05,
        "state": "refunded"
      }
    ],
    "count": 1
  },
  "error": ""
}

GET /dashboard/api/translate/notifications

Returns unread notification count and recent completed job summaries for the authenticated user's translation API key.

Response (200 OK)

{
  "status_code": 200,
  "data": {
    "unread_count": 2,
    "notifications": [
      {
        "job_id": "019e5bdc36a5-c87d32a56bc39bee",
        "completed_at": "2026-05-24T21:25:00Z",
        "state": "succeeded",
        "docs": ["Trinity-Beast-Translation-Service.html"],
        "langs": 11,
        "succeeded_pairs": 11,
        "failed_pairs": 0
      }
    ]
  },
  "error": ""
}

POST /dashboard/api/translate/notifications/seen

Marks all notifications as seen. Resets the badge count to 0. No request body required.

Response (200 OK)

{
  "status_code": 200,
  "data": {
    "message": "Notifications marked as seen"
  },
  "error": ""
}

16. i18n Key Translation API

Automated multi-lingual JSON key translation for the website's internationalization system. Detects missing keys across all 11 target languages and fills them via Amazon Bedrock (Claude) or manual injection. The website serves language JSON from Valkey via GET /public/lang/{code} — this endpoint keeps all languages in sync with English.

16.1 Translate i18n Keys

Detects missing keys and translates them. Bedrock mode is async (fire-and-forget) — returns a job ID immediately and processes in the background. Manual mode and dry-run are synchronous.

Request Body

Example — Bedrock Mode (Async)

POST /admin/translate-i18n-keys
X-Admin-Key: {admin_key}
Content-Type: application/json

{
  "namespace": "translate",
  "target_langs": ["all"]
}

Response (202 Accepted)

{
  "status": "✅ [LPO] [us-east-2] [BeastMain] [/admin/translate-i18n-keys] [202]",
  "status_code": 202,
  "data": {
    "status": "accepted",
    "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "mode": "bedrock",
    "namespace": "translate",
    "source_keys": 62,
    "target_langs": ["es","pt","fr","de","ru","hi","ur","it","ar","ja","zh"],
    "message": "Translation job started. Poll /admin/translate-i18n-keys/status/{job_id} for progress."
  }
}

Example — Dry Run (Sync)

POST /admin/translate-i18n-keys
X-Admin-Key: {admin_key}
Content-Type: application/json

{
  "namespace": "*",
  "dry_run": true,
  "target_langs": ["es","ja"]
}

Response (200 OK)

{
  "data": {
    "status": "dry_run",
    "namespace": "*",
    "source_keys": 1583,
    "languages": [
      {"lang": "es", "missing_keys": ["dailyReports.loadError", "..."], "status": "dry_run"},
      {"lang": "ja", "missing_keys": ["dailyReports.loadError", "..."], "status": "dry_run"}
    ]
  }
}

Example — Manual Mode (Sync)

POST /admin/translate-i18n-keys
X-Admin-Key: {admin_key}
Content-Type: application/json

{
  "mode": "manual",
  "namespace": "translate",
  "target_langs": ["all"],
  "keys": {
    "translate.hero.title": {
      "es": "Motor de Traducción",
      "pt": "Motor de Tradução",
      "fr": "Moteur de Traduction",
      "de": "Übersetzungsmaschine",
      "ru": "Движок перевода",
      "hi": "अनुवाद इंजन",
      "ur": "ترجمہ انجن",
      "it": "Motore di Traduzione",
      "ar": "محرك الترجمة",
      "ja": "翻訳エンジン",
      "zh": "翻译引擎"
    }
  }
}

16.2 Check Translation Job Status

Poll the status of an async Bedrock translation job. Jobs are stored in Valkey with a 24-hour TTL.

Response (200 OK)

{
  "data": {
    "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "completed",
    "mode": "bedrock",
    "namespace": "translate",
    "source_keys": 62,
    "target_langs": ["es","pt","fr","de","ru","hi","ur","it","ar","ja","zh"],
    "started_at": "2026-05-22T19:10:00Z",
    "completed_at": "2026-05-22T19:12:34Z",
    "total_translated": 682,
    "languages": [
      {"lang": "es", "translated": 62, "status": "ok"},
      {"lang": "pt", "translated": 62, "status": "ok"},
      {"lang": "fr", "translated": 62, "status": "ok"}
    ]
  }
}

16.3 Supported Languages

16.4 How It Works

1. Reads lang:en from Valkey (source of truth for all i18n keys)
2. Flattens nested JSON into dot-notation keys (e.g., translate.hero.title)
3. For each target language, reads lang:{code} and identifies missing keys
4. Bedrock mode: translates in batches of 15 keys per API call (reliable JSON output)
5. Validates every key survives the round-trip (falls back to English if Bedrock drops one)
6. Merges translations into the existing language JSON (preserves all other keys)
7. Writes updated JSON back to Valkey — immediately available via GET /public/lang/{code}

16.5 Notes

• Brand terms (The Trinity Beast, CPMP, exchange names, etc.) are never translated
• Technical terms (API, WebSocket, JSON) stay in English when no natural equivalent exists
• Bedrock model: Claude Sonnet 4.6 (us.anthropic.claude-sonnet-4-6)
• Cost: approximately $0.001 per 15-key batch — under $0.25 for a full 11-language run
• Job status stored in Valkey key i18n:job:{job_id} with 24-hour TTL
• After translation, run bash scripts/kcc.sh push-langs to sync Valkey → S3 if needed