Auto-generated. This article is rebuilt from FastAPI route introspection by scripts/build_api_kb.py. Edit the route docstring in app/ and re-run the script — do not edit this file directly.

GET /api/v1/screener/company-action-board

Handler: app.screener.routes.get_company_action_board
Methods: GET

Description

Company Action Board — the pick-contract POSITION BOOK (W2-2).

longs/shorts are the OPEN pick contracts: picks that locked on a ripe + board-slot win and hold until ONE of three exits — horizon elapsed (the archetype’s payoff-profile hold, in trading bars), a close beyond the entry ∓ 1.5× entry-day-ATR invalidation level, or an adverse macro regime-band extreme. A pick NEVER leaves on a missed re-fire or a conviction flap — the board is a position book, not a daily re-rank. Each row’s contract sub-object carries the live contract state (entry ref, invalidation level, day k/H countdown); the row’s conviction/trust/board_score are the AS-OF-LOCK snapshot.

competing carries today’s ripe candidate rows (the candidate view — same shape, contract null) vying for open slots; locks happen at the twice-daily screener runs, never at read time (this route is read-only).

How the candidate view is built (competing rows + lock eligibility)

The engine reads active screener_candidates rows (status new or persisting), computes a board_score for each as::

board_score = conviction × edge_weight × regime_tilt

• conviction — the candidate’s composite conviction score (0-100), itself derived from post-earnings drift signal, quality, and insider net-flow context from free public company data.
• edge_weight — an auto-calibrating tier based on realized track record: proven (cleared the sample floor AND has a demonstrated edge — a skeptical Bayesian lower bound on the archetype’s intent-aware overall excess-vs-market hit-rate, across all its picks, is above 50%; a real edge, not merely enough samples), watching (calibrating with limited history, OR calibrated but the edge is not yet demonstrated), or degraded (the worst-horizon excess hit-rate fallen below the floor — downweighted but not removed). The weighting adjusts automatically as new episodes mature; no manual tuning required.
• regime_tilt — asymmetric multiplier driven by the macro drawdown- risk band. A risk-off or elevated drawdown-risk reading suppresses long scores and amplifies short scores; a low-risk calm reading is symmetrical.

Each ticker appears at most once per side (deduplication by ticker across archetypes). The board is sorted by board_score descending within each side.

Response keys

schema_version — format version string (e.g. "2026.07").

as_of — ET ISO-8601 timestamp of the snapshot that produced this board. Refreshed twice per trading day (mid-session ~10:30 ET and post-close ~17:30 ET); may be from a prior session outside market hours.

regime_band — the macro drawdown-risk band at board-build time (low, elevated, high, or null when unavailable). Determines how the regime tilt multiplier is applied.

regime_note — a short human-readable description of the current regime state as it affected the board (e.g. "Calm regime — balanced board" / "Elevated drawdown risk — shorts amplified, longs lower-conviction").

longs — list of long-side action rows, sorted by board_score descending. Each row carries: ticker, archetype, archetype_label, direction (long_recovery), horizon (the edge timescale in days, may be null), horizon_label (e.g. "PEAD Beat Drift · 10d"), conviction (0-100), conviction_tier (high, medium, low), conviction_carried + conviction_carried_age (true + sessions when the conviction is inherited from the name’s last fresh deep-scan stamp), last_fired

• last_fired_sessions_ago (the last date the name actually fired and how many trading sessions ago that was — the board only serves names fired within the freshness window, ≤3 sessions by default), board_score, edge_weight_tier (proven / watching / degraded), trust (a per-archetype trust badge: {state, hit_rate, n_matured, label}), why (1-4 short strings summarising the signal basis), and maturity (a maturation string e.g. "maturing (3/10d)" while a fresh pick is still inside its horizon, else null), and bettability (the “would I bet money” chip — see below).

bettability — a per-pick {score, chip, gated, gate_reasons, factors}: one honest 0-100 score → a BETTABLE / WATCH / NO-BET chip. score = 100 · G · edge · √(conviction/100) · freshness · confluence · market (each factor 0-1). G is a hard-zero gate: the score is forced to 0 (⇒ NO-BET) unless the archetype has a demonstrated edge (its skeptical lower-bound hit-rate clears 50%), is not drift-degraded, the conviction is fresh (not carried), and the pick is ripe. edge rescales the same demonstrated-edge measure; conviction is sqrt-damped; freshness decays with sessions since last fired. The confluence and market factors are wired but held neutral (1.0) until validated. On locked position-book rows the chip reads the as-of-lock conviction against the archetype’s CURRENT edge (so a pick locked with an edge that has since decayed reads NO-BET); on competing rows it reads the live candidate. NO-BET = a disqualifying gate fired; WATCH = cleared every trust gate but the composite is marginal; BETTABLE = cleared every gate AND strong. Decision-support, never advice.

live_signal (PR-7, Scheme 4) — a per-pick conflict chip present ONLY on a locked book row whose SAME ticker is firing the OPPOSITE directional archetype live (a held long now firing short, or vice versa — a flip fire, typically from a degraded archetype the ripe board view suppresses): {conflict, locked_direction, live_direction, live_archetype, note}. SURFACE-ONLY — informational, NEVER an auto-exit (auto-closing on a flip fire would re-import the churn the position book was built to kill). A same-direction re-fire is confirmation, not a conflict, and shows no chip.

shorts — identical structure for short-side rows (direction short_fragility).

counts — {long, short, suppressed_long, suppressed_short, suppressed_stale, open_slots_long, open_slots_short, competing}: long/short count OPEN contracts (the book); open_slots_* are the free slots per side (regime cap − open contracts — calm caps are 3L/2S per D6b); competing counts today’s ripe candidates vying for them; suppressed_stale counts ripe names kept out of the candidate view for staleness (W1-5); suppressed_long / suppressed_short count eligible candidates that did not fit the candidate view’s slot caps.

empty_reason — non-null only when the BOOK is empty. Distinguishes “no locked picks yet — N competing” (cold start / all slots freed) from “nothing ripe at all”. Always null on a populated book.

Framing

The board is a 1-2 week swing grading surface, NOT trade advice. Every row is explicitly labelled as graded-not-advice. The underlying post- earnings drift edge is validated (positive rank-IC, name-clustered bootstrapped CI lower bound > 0) but calm-conditional — regime performance in a genuine drawdown regime is not yet measured. The calm_conditional caveat is surfaced in the trust badge when applicable.

Signal data is derived from public market data and free company filings only. No account-linked data vendors are named on this surface.

PUBLIC — market metadata only (no PII, no per-account data). Also the substrate for the homepage Company Action Board scoreboard.

Degrade-honest per DOCTRINE P0: any internal error returns 200 with an empty board and empty_reason set — NEVER raises 500.

Curl

curl -s https://bigclawd.com/api/v1/screener/company-action-board