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

overflow_long / overflow_short (2026.08.4) carry the ripe tail ranked BELOW the per-side slot cap, bounded by ripeness.overflow_display_max. Slots are sticky by design — a locked pick is never evicted for a better-ranked ripe name — so without these a ripe candidate below the cutoff had no identity on any surface, only the aggregate counts.suppressed_long / suppressed_short. Same row shape, contract null. DISPLAY-ONLY: never locked, never graded, never counted into longs/shorts/counts.

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, tier, archetype_tier, archetype_posterior, gated, tier_reasons, factors}. The chip is one of NO-BET / PROBATION / BETTABLE and carries its sizing meaning directly: NO-BET = watch only; PROBATION = real money, minimum ticket, sleeve only; BETTABLE = full sleeve size per the operator’s strategy rules.

The chip is the pick’s ARCHETYPE TIER, downgraded — never upgraded — by the pick’s own factors. The archetype tier comes from a live evidence posterior: P(the archetype’s true entry-day-cohort expectancy > 0), where the evidence unit is the ENTRY-DAY COHORT, never the episode (episodes fired the same day move together and are not independent bets). An archetype reaches PROBATION at 60% and BETTABLE at 80% AND at least 8 matured post-lock cohorts — imported historical evidence can lift an archetype to PROBATION at most, so BETTABLE must be earned live. A drift-degraded — or gauntlet-falsified (a sealed-holdout forward-grade inversion) — archetype caps at NO-BET whatever its long-run number, the gauntlet veto checked ahead of the drift veto. archetype_posterior surfaces {p_edge, cohorts_total, cohorts_post_lock, trend} so the evidence behind the chip is visible; p_edge is null when the shared pool is too thin to estimate honestly.

Pick-level downgrades: a hard gate (no conviction score, a carried/stale conviction, or a candidate outside its buy zone) forces NO-BET; a candidate that last fired 3+ trading sessions ago drops one tier. A locked position-book row skips the ripeness and staleness downgrades (an active position is not a fresh entry) but reads its archetype’s CURRENT tier — so a pick locked while its archetype was trusted reads NO-BET once that archetype degrades. tier_reasons names every cause as a stable machine code, archetype-level first.

score (0-100) rides along as a transparency companion, unchanged: 100 · G · edge · √(conviction/100) · freshness · confluence · market. It still hard-zeros on the older binary demonstrated-edge gate, so a pick may read PROBATION with a score of 0 — two different measures of the same archetype. Read sizing off the chip, not the score. 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