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, Bitstamp, Kraken, Gate.io, Crypto.com, OKX) — 357 prewarmed assets pushed in real-time with zero REST polling. REST fallback (Coinbase → Kraken → Bitstamp) 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 Reporting 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,
    "bitstamp": 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
  bitstamp     100

4. Supported Assets & Exchanges

The Trinity Beast LPO serves 357 prewarmed assets across 6 exchanges via persistent WebSocket connections. Per-exchange split reflects real liquidity ceilings: Bitstamp 48, Coinbase 66, Crypto.com 46, Gate.io 65, Kraken 65, OKX 67. 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

Bitstamp (29 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 Account Endpoints (Bearer Token)

Dashboard Webhook Endpoints (Bearer Token)

Added 2026-08-07 through 2026-08-11 alongside the webhook Delivery Log, Delivery Reports, and dashboard-native activation features (see Trinity-Beast-Account-Dashboards.html §5.5).

The public-API mirror of the three webhook-reports endpoints lives at GET /webhook/reports/daily, /webhook/reports/summary, and POST /webhook/reports/refresh — same behavior, authenticated by API key rather than dashboard session, and (deliberately) not gated by LRS entitlement.

Dashboard Partner Endpoints (Bearer Token)

Partner connection management. Available to accounts with a Partner-tier key. No asset cap — partner access is unlimited by policy; the watchlist is purely organizational.

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))

{
  "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": "YOUR_API_KEY",
  "ip_address": "203.0.113.42",
  "agent_profile_arn": "arn:tbi:us-east-2:211998422884:agent-profile/tbi/v1",
  "timestamp": "2026-07-30T19:22:14Z",
  "data": {
    "asset": "BTC",
    "price": 64762.93,
    "source": "coinbase-ws",
    "cached": true,
    "monthly_usage": 37862,
    "monthly_limit": 999999999,
    "usage_pct": 0.0,
    "usage_warning": ""
  },
  "error": ""
}

# 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.

Search Response — Before and After

// BEFORE — bare payload (no longer returned)
{ "query": "webhook", "results": [ ... ], "count": 12, "elapsed": "3.1ms" }

// AFTER — standard envelope, payload under data
{
  "status": "✅ [LPO] [us-east-2] [BeastMain] [/search] [200]",
  "status_code": 200,
  "endpoint": "/search",
  "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-07-29T20:14:00Z",
  "data": {
    "query": "webhook",
    "results": [
      { "title": "API Reference", "section": "Webhook Push", "url": "/docs/...", "snippet": "...", "score": 27 }
    ],
    "count": 12,
    "elapsed": "3.1ms"
  },
  "error": ""
}

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,
        "rhema_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 provisioned in AWS Secrets Manager (trinity-beast-admin-secrets) and nowhere else. If no key is loaded, every admin endpoint refuses the request.

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.

GET /asset-categories — Response Shape

Public endpoint, no auth. Returns all enabled assets grouped by category with icon URLs. Cache: 5 min.

{
  "status": "✅ [LPO] [us-east-2] [BeastMain] [/asset-categories] [200]",
  "status_code": 200,
  "data": {
    "categories": [
      {
        "name": "Major Currencies",
        "description": "Top market cap assets",
        "display_order": 1,
        "assets": ["BTC", "ETH", "SOL", "XRP", "ADA"],
        "icons": {
          "BTC": "https://coin-images.coingecko.com/coins/images/1/large/bitcoin.png",
          "ETH": "https://coin-images.coingecko.com/coins/images/279/large/ethereum.png",
          "SOL": "https://coin-images.coingecko.com/coins/images/4128/large/solana.png"
        }
      },
      {
        "name": "DeFi",
        "description": "Decentralized finance protocols",
        "display_order": 2,
        "assets": ["UNI", "AAVE", "MKR", "CRV"],
        "icons": {
          "UNI": "https://coin-images.coingecko.com/coins/images/12504/large/uni.png",
          "AAVE": "https://coin-images.coingecko.com/coins/images/12645/large/aave.png"
        }
      }
    ],
    "total_assets": 357
  },
  "error": ""
}

GET /asset-categories?full=1 — Uncapped Mode

By default each category is trimmed to 9 assets (ranked by 30-day request volume from usage_logs, alphabetical tiebreak) to keep the demo dropdown compact. Passing full=1 skips the trim entirely and returns every enabled asset in every category — the mode the Webhook and Partner dashboard asset pickers use, since a Professional or Enterprise subscriber needs to see the whole pool, not just the top 9 per category. Cache is 15 minutes in this mode (vs 5 minutes capped) since the full response is larger and changes less often.

GET /asset-names — Response Shape

Public endpoint, no auth. Returns the human-readable display name for every asset symbol, sourced from exchange_asset_map.display_name (backfilled from CoinGecko). Used by the dashboard asset pickers to show a name on hover (e.g. hovering BTC shows "Bitcoin").

{
  "status": "✅ [LPO] [us-east-2] [BeastMain] [/asset-names] [200]",
  "status_code": 200,
  "data": {
    "names": {
      "BTC": "Bitcoin",
      "ETH": "Ethereum",
      "SOL": "Solana"
    }
  },
  "error": ""
}

POST /admin/eam/discover — Response Shape (poll result)

{
  "ready": true,
  "result": {
    "exchange": "okx",
    "candidates": [
      {
        "asset": "MON",
        "exchange_symbol": "MON-USDT",
        "price": 0.0237,
        "volume_24h": 21862.50,
        "exchange": "okx",
        "category": "Meme Coins",
        "icon_url": "https://coin-images.coingecko.com/coins/images/..."
      }
    ],
    "grouped": {
      "Meme Coins": [{"asset": "MON", "...": "..."}],
      "DeFi": [{"asset": "SPELL", "...": "..."}],
      "Infrastructure": [{"asset": "FLUX", "...": "..."}]
    },
    "covered_total": 171,
    "exchange_total": 400,
    "uncovered": 229,
    "scored": 40
  }
}

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: TBI Translation Engine.

Job Submission

Monitoring

Control

Cost Protection — 429 Responses

The submit handler enforces two independent daily caps. Either can trigger a 429 on /admin/translate. For customer accepts (15.5, 15.6), the kill switch and both caps are also checked before the charge, and a tripped guard answers 503 tbts_service_paused with nothing charged, so no customer ever pays for a job a guard would stop:

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

Language Catalog

Gates /translate/quote, accept and admin submit. The catalog holds 127 languages: the 75 rows of Amazon Translate's published list joined with the 119 languages Qwen 3 publishes. Input codes are 2–12 characters (a primary code, an optional script, an optional region), and 36 alternate codes such as nb, zh-Hant and ar-EG are converted silently. A code that has a valid shape but is not in the catalog is rejected before any document analysis, pricing or charge. See architecture.md for the full incident this closes.

Valkey cache, two keys: tx:supported_langs (hash, lang_code → status, synced nightly by BeastReconciler) and tx:lang_catalog (the full catalog as JSON, TTL 27 hours). Every LPO container also refreshes its catalog in place every 15 minutes (timer txlangs_refresh), so a change reaches every container without a deploy. If Aurora and both Valkey keys are unreachable the catalog is empty and a quote answers 503 tbts_langs_unavailable — it fails closed, and nothing is ever charged for a language we can't confirm.

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 every technical identifier, into and out of any of 127 languages. Six AI agents are available: five at the same flat $3.00 per document-language pair, and Claude Opus 4.8 priced at its actual cost with a $3.00 floor. The engine is agent-agnostic, so any model reachable through Amazon Bedrock can serve as an agent without code changes.

The flow is quote → accept → follow the status → download. Along the way you can cancel any time before a job finishes, retry failed pairs once at no charge, and you are refunded automatically for anything that still can't be delivered. Every promise in that sentence is backed by an endpoint below, so an integration can do everything the dashboard can. The Translation Service document walks through it end to end.

15.1 GET /translate/models

Lists the six translation agents. Public — no authentication required. Use an id as the model in a quote; leave model out and you get Auto, the best agent per language: the agent named in default (Qwen 3 235B) for every language it supports, and Claude Sonnet 4.6 only for Amharic, Hausa, Mongolian, Pashto and Somali, at the same price. Naming an agent overrides Auto for every language, retries included.

Response (200 OK)

{
  "status_code": 200,
  "data": {
    "models": [
      { "id": "qwen3-235b",        "name": "Qwen 3 235B",       "tier": "Fast & Capable",   "input_rate_per_1m": 0.22,  "output_rate_per_1m": 0.88,  "estimated_cost_per_pair": 0.019294, "speed": "fast",     "quality": "good",        "description": "Fast and capable. Excellent with Chinese, Japanese, and Korean. The default choice." },
      { "id": "deepseek-v3",       "name": "DeepSeek V3",       "tier": "Fast & Capable",   "speed": "fast",     "quality": "good",        "description": "Fast and capable. Strong with European languages and technical content." },
      { "id": "mistral-large",     "name": "Mistral Large",     "tier": "Fast & Capable",   "speed": "fast",     "quality": "good",        "description": "Fast and capable. Native-quality Romance languages (French, Spanish, Portuguese, Italian)." },
      { "id": "claude-haiku-5.5",  "name": "Claude Haiku 5.5",  "tier": "Fast & Capable",   "speed": "fast",     "quality": "good",        "description": "Fast and capable. Versatile all-rounder, great for high-volume jobs." },
      { "id": "claude-sonnet-4.6", "name": "Claude Sonnet 4.6", "tier": "Deep Reasoning",   "speed": "moderate", "quality": "excellent",   "description": "Deep reasoning, nuanced output. Handles complex scripts (Arabic, Hindi, Japanese) and technical documents well." },
      { "id": "claude-opus-4.8",     "name": "Claude Opus 4.8",     "tier": "Maximum Fidelity", "input_rate_per_1m": 5.50, "output_rate_per_1m": 27.50, "estimated_cost_per_pair": 0.5731, "speed": "slow",     "quality": "exceptional", "description": "Highest quality, comprehensive translation. Best for critical documents, nuanced content, and languages with complex grammar." }
    ],
    "default": "qwen3-235b",
    "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."
  }
}

Every agent entry carries all nine fields; the first and the Claude Opus 4.8 entry are shown in full and the rest are abbreviated here for width. Opus 4.8's rates (5.50 / 27.50 USD per million tokens, refreshed nightly from the AWS Price List) put a typical 50 KB document at about $0.57 of our cost, so it is priced at the $3.00 floor until a document reaches about 200 KB. The earlier agent IDs claude-haiku-3.5 and claude-opus-4 are still accepted everywhere a model is taken, and are converted quietly to claude-haiku-5.5 and claude-opus-4.8, so an older integration never breaks.

15.2 POST /translate/quote

Send document URLs and target languages and receive a fixed price. The engine fetches and analyzes each document (size, sections, code blocks, diagrams), resolves every language against the 127-language catalog (alternate codes such as nb or zh-Hant are converted quietly), works out each document's source language, and refuses a target that equals the source. Nothing is charged at this step.

Request Body

{
  "docs": ["https://your-site.com/docs/api-reference.html", "https://your-site.com/docs/faq.html"],
  "langs": ["es", "fr", "de", "ja", "zh-TW"],
  "source_lang": "en",
  "source_langs": { "https://your-site.com/docs/faq.html": "it" },
  "model": "qwen3-235b"
}

How the Source Language Is Decided

For each document the first of these that gives an answer wins, and source_provenance records which one it was: stated (your source_langs or source_lang), declared (the page's <html lang>, with region tags reduced, so en-US is English and ar-EG is Modern Standard Arabic), detected (only a definitive detection counts: English by word frequency, and Japanese, Korean or Thai by script), otherwise auto. A declared language that a definitive detection contradicts becomes auto rather than a guess. An unsure source never fails a quote: the document gets source_lang_confirm_needed: true and a source_hint in your api_lang, and the agent translates from the document's original language as written.

Response (200 OK)

{
  "status_code": 200,
  "data": {
    "quote_id": "qt-a1b2c3d4-e5f",
    "docs": [
      {
        "doc_url": "https://your-site.com/docs/api-reference.html",
        "doc_name": "api-reference.html",
        "analysis": { "size_bytes": 63488, "estimated_chunks": 4, "difficulty": "moderate", "code_blocks": 12, "diagrams": 2 },
        "total_price": 15.00
      },
      {
        "doc_url": "https://your-site.com/docs/faq.html",
        "doc_name": "faq.html",
        "analysis": { "size_bytes": 18944, "estimated_chunks": 2, "difficulty": "simple", "code_blocks": 0, "diagrams": 0 },
        "total_price": 15.00
      }
    ],
    "doc_count": 2,
    "languages": ["es", "fr", "de", "ja", "zh-TW"],
    "lang_count": 5,
    "total_pairs": 10,
    "model": "qwen3-235b",
    "auto_routed": false,
    "model_by_lang": {},
    "delivery": { "mode": "express", "label": "Express — real-time translation", "estimated_time": "~8 minutes", "qualified_reason": "10 translated documents (2 docs × 5 languages)" },
    "pricing": { "price_per_pair": 3.00, "total_pairs": 10, "total_price": 30.00, "currency": "USD" },
    "expires_at": "2026-10-13T15:00:00Z",
    "accept_url": "/translate/accept/qt-a1b2c3d4-e5f",
    "sources": [
      { "doc_url": "https://your-site.com/docs/api-reference.html", "doc_name": "api-reference.html", "source_lang": "en", "source_provenance": "stated", "source_lang_confirm_needed": false, "source_hint": "" },
      { "doc_url": "https://your-site.com/docs/faq.html", "doc_name": "faq.html", "source_lang": "it", "source_provenance": "stated", "source_lang_confirm_needed": false, "source_hint": "" }
    ],
    "superseded_quote_id": ""
  }
}

model_by_lang is {} when you chose an agent, and the per-language map when the quote was auto-routed (model: "per-language", auto_routed: true). Internal AI cost is never part of the response: you see the price and nothing else.

Error Responses

15.3 GET /translate/quote/{quote_id}

Returns one quote with its current state: pending, accepted, expired, superseded (a newer quote replaced it; superseded_by names it, or is "" when the document now breaks a rule), refunded or partially_refunded.

Response (200 OK)

{
  "status_code": 200,
  "data": {
    "quote_id": "qt-a1b2c3d4-e5f",
    "doc_url": "https://your-site.com/docs/api-reference.html",
    "doc_name": "api-reference.html",
    "docs": [
      { "url": "https://your-site.com/docs/api-reference.html", "name": "api-reference.html" },
      { "url": "https://your-site.com/docs/faq.html", "name": "faq.html" }
    ],
    "doc_count": 2,
    "languages": ["es", "fr", "de", "ja", "zh-TW"],
    "total_pairs": 10,
    "model": "qwen3-235b",
    "analysis": { "size_bytes": 63488, "estimated_chunks": 4, "difficulty": "moderate", "code_blocks": 12, "diagrams": 2 },
    "pricing": { "price_per_pair": 3.00, "pairs": 10, "total_price": 30.00, "currency": "USD" },
    "sources": [
      { "doc_url": "https://your-site.com/docs/api-reference.html", "doc_name": "api-reference.html", "source_lang": "en", "source_provenance": "stated", "source_lang_confirm_needed": false, "source_hint": "" },
      { "doc_url": "https://your-site.com/docs/faq.html", "doc_name": "faq.html", "source_lang": "it", "source_provenance": "stated", "source_lang_confirm_needed": false, "source_hint": "" }
    ],
    "state": "accepted",
    "superseded_by": "",
    "expires_at": "2026-10-13T15:00:00Z",
    "accepted_at": "2026-10-10T15:04:12Z",
    "job_id": "019e4b8a37bc-1f2e3d4c5b6a7980"
  }
}

pricing.pairs is documents × languages, so a multi-document quote always shows its true pair count. doc_url, doc_name and analysis describe the first document and are kept for older integrations; docs lists them all.

15.4 GET /translate/quotes

Your 30 most recent quotes for this API key, newest first. data is the array itself. A quote replaced by a newer one appears with state: "superseded".

Response (200 OK)

{
  "status_code": 200,
  "data": [
    { "quote_id": "qt-a1b2c3d4-e5f", "doc_name": "api-reference.html",      "lang_count": 5, "total_price": 30.00, "state": "accepted", "expires_at": "2026-10-13T15:00:00Z", "job_id": "019e4b8a37bc-1f2e3d4c5b6a7980", "model": "qwen3-235b" },
    { "quote_id": "qt-f6e5d4c3-b2a", "doc_name": "architecture-guide.html", "lang_count": 3, "total_price": 9.00,  "state": "pending",  "expires_at": "2026-10-13T18:00:00Z", "job_id": "",                    "model": "claude-sonnet-4.6" }
  ]
}

15.5 POST /translate/accept/{quote_id}

Accepts a pending quote. No request body is needed. Before the card on file is touched, the engine claims the quote so a double-click can't charge twice, re-checks every limit, checks the service guards, and fetches every document again to compare it with what was priced. Only then is the quoted total charged and the job started.

Response (200 OK)

{
  "status_code": 200,
  "data": {
    "status": "accepted",
    "quote_id": "qt-a1b2c3d4-e5f",
    "job_id": "019e4b8a37bc-1f2e3d4c5b6a7980",
    "model": "qwen3-235b",
    "payment_id": "pi_3abc123def456",
    "amount_usd": 30.00,
    "status_url": "/translate/status/019e4b8a37bc-1f2e3d4c5b6a7980",
    "notice": "",
    "notice_key": "",
    "updated_docs": [],
    "key": "",
    "message": "",
    "refunded": false,
    "refund_amount": 0
  }
}

Every field is always present. When a document's readable content changed but its price and rule results did not, the job still starts at the quoted price on the current version: notice_key is tbts_quote_content_updated, notice says so in your api_lang, and updated_docs names the documents. On Claude Opus 4.8, a re-quoted document that changes again is charged at the lower of the two prices, with tbts_quote_price_held.

When the Charge Succeeds but the Start Doesn't

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 9 quotes per batch. Every quote is claimed, re-checked and re-fetched exactly as in 15.5 before the card is touched.

Request Body

{
  "quote_ids": [
    "qt-a1b2c3d4-e5f",
    "qt-b2c3d4e5-f6a",
    "qt-c3d4e5f6-a7b"
  ]
}

Parameters

Response (200 OK)

{
  "status_code": 200,
  "data": {
    "status": "accepted",
    "batch_size": 3,
    "quote_ids": ["qt-a1b2c3d4-e5f", "qt-b2c3d4e5-f6a", "qt-c3d4e5f6-a7b"],
    "task_id": "019e4b8a37bd-0a1b2c3d4e5f6a7b",
    "task_status_url": "/translate/task/019e4b8a37bd-0a1b2c3d4e5f6a7b",
    "jobs": [
      { "quote_id": "qt-a1b2c3d4-e5f", "doc_name": "api-reference.html", "job_id": "019e4b8a37bc-1f2e3d4c5b6a7980", "error": "", "key": "", "status_url": "/translate/status/019e4b8a37bc-1f2e3d4c5b6a7980", "refunded": false, "refund_amount": 0, "notice": "", "notice_key": "", "updated_docs": [] },
      { "quote_id": "qt-b2c3d4e5-f6a", "doc_name": "quick-start.html", "job_id": "019e4b8a37be-2c3d4e5f6a7b8c9d", "error": "", "key": "", "status_url": "/translate/status/019e4b8a37be-2c3d4e5f6a7b8c9d", "refunded": false, "refund_amount": 0, "notice": "", "notice_key": "", "updated_docs": [] },
      { "quote_id": "qt-c3d4e5f6-a7b", "doc_name": "webhooks.html", "job_id": "019e4b8a37bf-3d4e5f6a7b8c9d0e", "error": "", "key": "", "status_url": "/translate/status/019e4b8a37bf-3d4e5f6a7b8c9d0e", "refunded": false, "refund_amount": 0, "notice": "", "notice_key": "", "updated_docs": [] }
    ],
    "payment_id": "pi_3abc123def456",
    "amount_usd": 42.00,
    "eta": {
      "estimated_seconds": 540,
      "estimated_low_seconds": 420,
      "estimated_high_seconds": 660,
      "estimated_formatted": "~9 minutes",
      "estimated_range": "7-11 minutes",
      "bottleneck_lang": "ja",
      "elapsed_seconds": 0,
      "remaining_seconds": 540,
      "remaining_formatted": "~9 minutes",
      "percent_complete": 0
    },
    "key": "",
    "message": ""
  }
}

In this example the three quotes cover 5, 3 and 6 document-language pairs: 14 pairs at the flat $3.00 is one charge of 42.00. task_status_url follows the whole batch (15.9), and each job's status_url follows that job (15.8). The eta is the slowest job in the batch, so it tells you when everything will be done.

Each jobs[] entry reports its own start, so one quote that can't start never holds the others back. A quote that couldn't start has an empty job_id, key tbts_translation_start_refunded (or tbts_status_refund_delayed, or tbts_translation_start_pending while we confirm), refunded and refund_amount for what came back, and a status_url that uses the quote ID. When no quote in the batch could start, the response is 502 with status: "start_failed" and the same jobs list, and the task still exists so GET /translate/task/{task_id} reports the refunds.

Error Responses

15.7 POST /translate/cancel/{quote_id}

Changed your mind after accepting a quote? You can stop the translation at any point before it finishes, and you pay only for what you received. Every document-language pair already delivered is yours to keep. Every pair that was not delivered is refunded at its full per-pair price. No request body is needed; authenticate with the same API key you use for the rest of /translate/*.

Request

curl -X POST -H "X-API-Key: your-api-key-here" \
     https://api.cpmp-site.org/translate/cancel/qt-a1b2c3d4-e5f

Response (200 OK)

{
  "status": "✅ [LPO] [us-east-2] [BeastMain] [/translate/cancel/qt-a1b2c3d4-e5f] [200]",
  "status_code": 200,
  "data": {
    "quote_id": "qt-a1b2c3d4-e5f",
    "job_id": "019e4b8a37bc-1f2e3d4c5b6a7980",
    "state": "cancelled",
    "refund_status": "calculating",
    "message": "Translation cancelled. Pages already delivered are yours to keep. The refund for the rest is being calculated."
  },
  "error": ""
}

What Happens After You Cancel

The cancel takes effect the moment you send it, but the engine never cuts a language off mid-sentence. Each language finishes the section it is working on and stops at that boundary, so a page is either fully delivered or not delivered at all. You will never receive half a translation. On a large document one section can take up to about three minutes, and that short wait is what keeps every delivered page whole.

Once the last language has stopped, the refund is fixed by counting what was actually delivered. Your refund_status then moves through these states:

You get one email when the refund is issued. It tells you which languages were delivered, which were stopped, and the amount coming back to you. The Account Dashboard shows the same refund state live, and a cancelled job stays in your Translation History with the refunded amount under its price.

Error Responses

Cancelling a Free Retry

When the job that is running is your free retry (15.10), cancel stops only the retry. The answer is 200 with tbts_cancel_retry_accepted ("The retry was cancelled. Anything it didn't finish will be refunded automatically."), refund_status stays "", and no approval is involved: the retry was free, so the pairs neither the job nor the retry delivered go straight to the automatic failed-pair refund.

15.8 GET /translate/status/{job_id}

Live status of one translation: every document-language pair, the ETA while it runs, the free retry, and any refund. The path accepts a job ID, a retry job ID, or a quote ID (the form a start-failure response points at). Authentication is the same as the rest of /translate/*, and ownership is by your account, so any of your keys can read any of your jobs. Pair progress is read from Valkey first, so polling stays fast, with Aurora as the fallback; money and refund state always come from Aurora.

Response (200 OK)

{
  "status_code": 200,
  "data": {
    "job_id": "019e4b8a37bc-1f2e3d4c5b6a7980", "quote_id": "qt-a1b2c3d4-e5f", "parent_job_id": "019e4b8a37bc-1f2e3d4c5b6a7980",
    "state": "partial", "job_state": "partial",
    "model": "per-language", "model_by_lang": { "es": "qwen3-235b", "zh-TW": "qwen3-235b" }, "model_display": "Qwen 3 235B",
    "submitted_at": "2026-10-10T15:04:13Z", "started_at": "2026-10-10T15:04:20Z", "completed_at": "2026-10-10T15:12:40Z",
    "docs": ["api-reference.html"], "langs": ["es", "zh-TW"], "total_pairs": 2,
    "counts": { "queued": 0, "running": 0, "succeeded": 1, "failed": 1, "cancelled": 0 },
    "pairs": [
      { "doc": "api-reference.html", "lang": "es",    "state": "succeeded", "job_id": "019e4b8a37bc-1f2e3d4c5b6a7980", "attempts": 1 },
      { "doc": "api-reference.html", "lang": "zh-TW", "state": "failed",    "job_id": "019e4c02d9f1-6b5a4c3d2e1f0a9b", "attempts": 2 }
    ],
    "eta": null,
    "retry": { "allowed": false, "state": "closed", "retry_job_id": "019e4c02d9f1-6b5a4c3d2e1f0a9b", "window_ends_at": "" },
    "cancel_refund": { "status": "", "amount_due": 0, "amount_refunded": 0 },
    "failed_pair_refund": { "status": "issued", "amount_due": 0, "amount_refunded": 3.00, "pairs": [{ "doc": "api-reference.html", "lang": "zh-TW" }], "window_ends_at": "", "refunded_at": "2026-10-10T15:30:02Z" },
    "refund_status": "issued", "refund_due": 0, "total_refunded": 3.00,
    "downloads_ready": true, "download_url": "/translate/download/019e4b8a37bc-1f2e3d4c5b6a7980",
    "message_key": "tbts_status_partial_refunded",
    "message": "1 of 2 translations couldn't be completed. We refunded 3.00 for them automatically."
  }
}

Every field is always present and every list is [] rather than null. The full list of message_key values and what each one means is in the Translation Service document.

Error Responses

15.9 GET /translate/task/{task_id}

Live status of a whole batch from 15.6. Each job is reported with the same object as 15.8, built by the same code, so a batch and its jobs can never disagree.

{
  "status_code": 200,
  "data": {
    "task_id": "019e4b8a37bd-0a1b2c3d4e5f6a7b", "state": "running", "submitted_at": "2026-10-10T15:04:13Z",
    "total_jobs": 3,
    "counts": { "queued": 0, "running": 1, "succeeded": 1, "partial": 1, "failed": 0, "cancelled": 0 },
    "jobs": [ "<one 15.8 status object per job>" ],
    "total_pairs": 14, "succeeded_pairs": 11, "failed_pairs": 1,
    "total_refunded": 0, "eta": { "estimated_seconds": 180, "remaining_formatted": "~3 minutes" },
    "message": "2 of 3 jobs finished."
  }
}

state is running while any job is active, then succeeded, partial or cancelled. eta is the slowest active job. A quote in the batch that was refunded because it couldn't start is reported too, with its refund. Not found or not yours → 404 tbts_task_not_found.

15.10 POST /translate/retry/{quote_id}

Your one free retry per quote. It runs only the retryable failed pairs again, on the agent the quote was priced for, at no charge. It is always available, whether or not automatic failed-pair refunds are switched on. A pair skipped because the document was already in that language is never retried, only refunded. No request body is needed.

{
  "status_code": 200,
  "data": {
    "quote_id": "qt-a1b2c3d4-e5f",
    "retry_job_id": "019e4c02d9f1-6b5a4c3d2e1f0a9b",
    "state": "queued",
    "pairs": [{ "doc": "api-reference.html", "lang": "zh-TW" }],
    "status_url": "/translate/status/019e4c02d9f1-6b5a4c3d2e1f0a9b",
    "message": "Retrying 1 translations at no charge."
  }
}

15.11 POST /translate/refund-failed/{quote_id}

"Refund instead": you decline the free retry and ask for the failed pairs to be refunded now. It moves the quote's failed_pair_refund.status from window_open to due and issues the refund straight away. Each failed pair is refunded at exactly its own price, in whole cents with any rounding going to you, and the refund can never be sent twice. No request body and no approval step.

{
  "status_code": 200,
  "data": {
    "quote_id": "qt-a1b2c3d4-e5f",
    "failed_pair_refund": { "status": "issued", "amount_due": 0, "amount_refunded": 3.00, "pairs": [{ "doc": "api-reference.html", "lang": "zh-TW" }], "window_ends_at": "", "refunded_at": "2026-10-10T15:20:41Z" },
    "message": "Refund requested for 1 translations. It's being processed now."
  }
}

15.12 GET /translate/languages — Supported Languages

127 languages, every one usable as a source or a target, English included, translated directly from one to the other with no pivot through a third language. The list below is generated from the same catalog the quote checks; a code that isn't on it is refused before anything is priced or charged.

GET /translate/languages returns it live. It is public (no key) and cacheable for five minutes (Cache-Control: public, max-age=300), so your integration never has to hard-code the list:

{
  "status_code": 200,
  "data": {
    "count": 127,
    "languages": [
      { "code": "af", "english_name": "Afrikaans", "native_name": "Afrikaans", "script": "Latn", "rtl": false, "word_spaced": true, "base_lang": "", "status": "supported" }
    ],
    "limits": { "max_langs_per_quote": 12, "max_docs_per_quote": 42, "max_doc_kb": 300, "max_quotes_per_batch": 9 },
    "aliases": { "nb": "no", "zh-Hant": "zh-TW", "ar-EG": "ar" },
    "source": "aurora"
  }
}

count is the number of languages you can order right now. languages lists every targetable row, and a row an operator has paused shows status: "blocked" rather than disappearing. source says where the catalog was read from (aurora, valkey or empty); an empty catalog answers 200 with count: 0, and a quote then answers 503 tbts_langs_unavailable rather than guessing.

• 15 right-to-left languages (rtl: true), such as Arabic and its dialects, Hebrew, Persian, Urdu and Pashto.
• 8 languages without spaces between words (word_spaced: false): Japanese, Chinese, Traditional Chinese, Cantonese, Thai, Lao, Khmer and Burmese.
• 36 alternate codes are converted quietly, in quotes and in stated sources alike. Arabic with a country tag means Modern Standard Arabic (ar); a dialect has its own code. The full list: nb → no, zh-Hant → zh-TW, zh-HK → zh-TW, zh-MO → zh-TW, zh-Hans → zh, zh-CN → zh, zh-SG → zh, ar-EG → ar, ar-MA → ar, ar-TN → ar, ar-SA → ar, ar-IQ → ar, ar-YE → ar, ar-SY → ar, ar-LB → ar, ar-JO → ar, ar-PS → ar, pt-BR → pt, pt-AO → pt-PT, pt-MZ → pt-PT, pt-CV → pt-PT, pt-GW → pt-PT, pt-ST → pt-PT, pt-TL → pt-PT, fil → tl, iw → he, in → id, ji → yi, prs → fa-AF, pes → fa, es-419 → es, sr-Cyrl → sr, uz-Latn → uz, az-Latn → az, pa-Guru → pa, mn-Cyrl → mn.

15.13 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-a1b2c3d4-e5f
X-Admin-Key: your-admin-key
Content-Type: application/json

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

Response (200 OK)

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

15.14 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.15 Dashboard Translation Endpoints

Authenticated dashboard endpoints for translation spend tracking, refund history, retries, refunds, downloads and job completion notifications. All require Bearer token authentication via the dashboard session. Every one of them reads across all of your translation keys, revoked keys included, so rotating a key never hides your history.

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-5.5": {"jobs": 3, "pairs": 24, "cost_usd": 9.60},
          "claude-sonnet-4.6": {"jobs": 6, "pairs": 48, "cost_usd": 79.20},
          "claude-opus-4.8": {"jobs": 1, "pairs": 6, "cost_usd": 43.20}
        }
      }
    ]
  },
  "error": ""
}

GET /dashboard/api/translate/refunds

Returns refund history for translation purchases. A customer sees their own refunds from every one of their translation keys; an admin sees every account. kind tells the three refund paths apart: failed_pairs (the automatic refund for incomplete translations), cancel and admin. refund_amount is the quote's running refunded_total.

Response (200 OK)

{
  "status_code": 200,
  "data": {
    "refunds": [
      {
        "quote_id": "qt-a1b2c3d4-e5f",
        "doc_name": "api-reference.html",
        "lang_count": 5,
        "model": "qwen3-235b",
        "original_price": "15.00",
        "refund_amount": "3.00",
        "refund_id": "re_1234567890",
        "state": "partially_refunded",
        "refunded_at": "2026-05-22T14:30:00Z",
        "accepted_at": "2026-05-22T13:58:10Z",
        "customer_email": "user@example.com",
        "kind": "failed_pairs"
      }
    ],
    "count": 1
  },
  "error": ""
}

POST /dashboard/api/translate/cancel/{job_id}

The endpoint behind the Cancel Translation button in your Account Dashboard. It follows the same policy and runs the same cancel path as POST /translate/cancel/{quote_id} (15.7), so the refund is identical whichever one you use. The only differences are that it takes the job_id your dashboard already holds and authenticates with your dashboard session instead of an API key. No request body is needed.

Response (200 OK)

{
  "status_code": 200,
  "data": {
    "job_id": "019e4b8a37bc-1f2e3d4c5b6a7980",
    "state": "cancelled",
    "refund_status": "calculating"
  },
  "error": ""
}

Refusals match 15.7: 404 when the job is not on your account, 409 when it has already been cancelled, has already finished, or was never accepted. Cancelling a running free retry stops only the retry, exactly as in 15.7.

POST /dashboard/api/translate/retry-failed/{job_id}

The Retry button: the one free retry per quote (15.10), started from the dashboard with the job ID it already holds. Always available.

{
  "status_code": 200,
  "data": {
    "job_id": "019e4c02d9f1-6b5a4c3d2e1f0a9b",
    "quote_id": "qt-a1b2c3d4-e5f",
    "state": "queued",
    "submitted_at": "2026-10-10T15:14:02Z",
    "retry_of": "019e4b8a37bc-1f2e3d4c5b6a7980",
    "docs": ["api-reference.html"],
    "langs": ["zh-TW"]
  },
  "error": ""
}

job_id here is the new retry job. Refusals use the dashboard error keys translate_retry_not_available, translate_retry_in_progress, translate_retry_closed and translate_retry_window_expired, with the same meanings as 15.10.

POST /dashboard/api/translate/refund-failed/{job_id}

The "Refund instead" button (15.11). Response {job_id, quote_id, pairs, failed_pair_refund}. If automatic failed-pair refunds are ever paused, it answers 404 translate_refund_failed_unavailable, and when there is nothing to refund, 409 translate_refund_failed_not_available.

GET /dashboard/api/translate/download/{job_id}

Signed download links for every delivered document and language, the same set as GET /translate/download/{job_id}. Allowed once no job of the quote is active and at least one pair was delivered, so partial and cancelled jobs can collect what they received.

GET /dashboard/api/translate/notifications

Returns unread notification count and recent completed job summaries across every translation API key of the authenticated user.

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