API reference

Swing Deck exposes two HTTP surfaces. The cloud API at api.swing-deck.com handles license validation, checkout, sync, and alerts. The local dashboard at http://localhost:8001 serves the audit data, runs the AI coaches, and brokers order placement against E*TRADE / Tradier. Most endpoints are called by the dashboard automatically — this reference is for custom integrations or if you're auditing the behavior.

⬢ Cloud API — api.swing-deck.com

Base URL

Production: https://api.swing-deck.com

Interactive OpenAPI: api.swing-deck.com/docs (FastAPI auto-generated)

Authentication

Three auth patterns exist. Use whichever the endpoint requires:

Endpoints

System

License

Billing

Trial

Alerts

Cloud sync

Referrals

v5.0 endpoints

Public endpoints added in v5.0. The consensus + daily-briefing endpoints require a valid license; track-record reads are public.

v6.4 endpoints (NEW · Founding 100 launch)

Public endpoints added with the v6.4 launch. Both are unauthenticated reads — they drive the live counter on /pricing and the tier-aware welcome page after Stripe checkout.

{
  "claimed":    12,
  "total":      100,
  "remaining":  88,
  "closed":     false
}

{
  "tier":            "founding",        // "founding" | "pro" | "premium" | "trial" | "unknown"
  "customer_email":  "you@example.com",
  "slot_number":     12,                 // founding only — null otherwise
  "slot_total":      100,                // founding only — null otherwise
  "downgraded_from_founding": false      // true iff the cap was hit during checkout and pro was issued instead
}

Rate limits

In-memory token bucket per (bucket, license_key_or_ip). Resets on deploy. Exceeding the limit returns 429 with a Retry-After header and a JSON body:

{
  "detail": {
    "error":       "rate_limit_exceeded",
    "bucket":      "alert_dispatch",
    "limit":       30,
    "window_sec":  3600,
    "retry_after": 120,
    "message":     "Rate limit: 30 per 1h"
  }
}

Error codes

Example — validating a key from bash

curl -X POST https://api.swing-deck.com/api/validate-license \
  -H "Content-Type: application/json" \
  -d '{"key": "SWING-XXXX-XXXX-XXXX"}'

# =>
# {
#   "valid": true,
#   "tier":  "pro",
#   "features": {"max_tickers": 25, "broker_writes": true, …},
#   "email":  "you@example.com",
#   "expires_at": null,
#   "days_remaining": null,
#   "message": "Active pro license"
# }

⬢ Local dashboard — http://localhost:8001

The local dashboard's HTTP server is the same one rendering the UI you click. It runs entirely on your machine — no traffic leaves localhost — and exposes endpoints for the audit data, the eight AI coaches, and the broker integration. Most of these are called automatically by the dashboard JS; this reference is for users who want to script against their own dashboard or build custom integrations.

CSRF token

Audit data

AI coaches (8 surfaces)

Each AI coach has the same endpoint shape: a GET that returns a cached narration if one exists, regenerating from the LLM only when the cache key bursts. Pass force=1 to bypass the cache. All eight coaches log to the same ai_thesis_log.jsonl on disk — see the history modal docs for the schema.

For the full input/output spec of each surface (cache keys, output shapes, hallucination guards), see the AI surfaces reference. The endpoints below are the call shape only.

Broker

Order placement endpoints are intentionally not documented for direct curl use. They run through an 8-layer pre-flight (audit-freshness, confirm-token, position-size cap, risk-budget cap, options-level enforcement, halt check, dry-run window, idempotency keys), and bypassing the dashboard UI defeats those guards. Use the dashboard's order modals instead. The endpoints below are the broker-state surface, which is safe to script against.

Mode toggle

Example — call a coach from bash

# 1. Fetch the CSRF token (only needed if you'll POST later;
#    /coach/* is GET so this step is skipped for read-only).
TOKEN=$(curl -s http://localhost:8001/csrf-token | python3 -c "import sys,json;print(json.load(sys.stdin)['token'])")

# 2. Generate the Trap & Structure narration for AAPL.
curl -s "http://localhost:8001/coach/trap_structure/generate?ticker=AAPL" | python3 -m json.tool

# =>
# {
#   "ticker":   "AAPL",
#   "state":    "FADE",
#   "verdict":  "WAIT",
#   "reason":   "Price tagged primary resistance at $269.77 with thin tape lean...",
#   "structure": { "primary_resistance": 269.77, "primary_support": 261.50, ... },
#   "exhaustion": { "rsi": 63, "momentum": "rolling_down" },
#   "tape":      { "lean_at_resistance": "thin" },
#   "better_entries": [{"price": 261.50, "reason": "support"}],
#   "cached":   false
# }