> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequency.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

# Sequency API reference (R\&D slice)

Curated reference for the Sequency backend (`sequency-api`, FastAPI) endpoints that
**strategy R\&D** uses — running backtests, defining/encoding strategies, reading
assessment verdicts, and pulling the market data / scores / levels that strategies
key off. This is a deliberate *slice* of the full \~431-endpoint surface, not the
whole API.

> Source of truth: [`openapi.json`](./openapi.json) (generated from the live app —
> see [Regenerating](#regenerating)). The group docs below are a hand-curated layer
> over that spec: they expand the schemas that matter for R\&D, fill in the response
> shapes for endpoints that declare no `response_model`, and organize endpoints by
> purpose. When the spec and a group doc disagree, the spec wins — re-curate the doc.

## Base URLs

| Environment    | Base                                                                         | Notes                                                                         |
| -------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Prod (on host) | `http://localhost:8081`                                                      | On the compute server (`compute.sequencyhq.com`).                             |
| Prod (public)  | Cloudflare-fronted hostnames (e.g. `api.sequency.sh` / `worker.sequency.sh`) | Origin is firewalled to Cloudflare ranges; do not hit the origin IP directly. |

## Auth model

Strict auth is enforced in prod (anonymous requests → `401`).

* **`/api/graph/v1/...`** (public app surface): requires a **Supabase JWT** (end user)
  **or** an **`X-Internal-Secret`** header (service principal).
* **`/api/internal/...`** (service-to-service): requires **`X-Internal-Secret`** only.
* `/health*` is exempt.

`X-Internal-Secret` is validated against a per-service map (`INTERNAL_SECRET_<NAME>`)
or the legacy `INTERNAL_API_SECRET`. For ad-hoc R\&D calls on the host, source it from
`/opt/sequency/.env` and pass it as the header (never print it).

## Group docs

| Doc                                                          | What it covers                                                                                                                                                                                                                                  |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [backtest.md](./backtest.md)                                 | **The R\&D core** — launch a backtest run, the request shape (universe, window, `bar_timeframe`, `strategy_rules`, exits, slippage, cost scales), the run lifecycle, and the results shape (metrics, equity curve, per-trade records, verdict). |
| [strategies.md](./strategies.md)                             | The **strategy rule DSL** (`StrategyRules` → entry groups → conditions → exits — how a strategy is encoded) plus strategy CRUD/list/health.                                                                                                     |
| [assessment.md](./assessment.md)                             | The credibility/assessment harness that produces deployability **verdicts** (deployable / marginal / insufficient\_data / reject) and its run-trigger.                                                                                          |
| [market-data.md](./market-data.md)                           | The **inputs** strategies consume: single-stock data, OHLCV/bars/chart, computed scores & indicators, market context, quotes/symbols.                                                                                                           |
| [screener-regime-intraday.md](./screener-regime-intraday.md) | Screener (candidate discovery), the 2×3-grid market **regime**, intraday **levels/profile** (VWAP/IB/OR/volume-profile), volume-nodes/compression, and outcome tracking.                                                                        |
| [pattern-events.md](./pattern-events.md)                     | The deterministic pattern corpus API — chart-annotation **insights** feed, search, lifecycle/scenarios (Track P). Operator-only (`admin_panel`-gated); included here because Track P scenario stats feed strategy R\&D expectancy.              |

## Regenerating

The committed `openapi.json` is produced from the running app (prod disables the
public `/openapi.json` route, so generate it via the app object):

```bash theme={null}
# on the API host (compute), against the deployed app:
cd /opt/sequency/api && set -a && source /opt/sequency/.env && set +a && \
  PYTHONPATH=/opt/sequency/api venv/bin/python -c \
  'import json; from app.main import app; json.dump(app.openapi(), open("/tmp/openapi.json","w"))'
# then copy /tmp/openapi.json -> docs/api/openapi.json
```

The group docs below are curated from the spec: each endpoint's request/response
shape is taken from `openapi.json` (`$ref`s resolved), and shapes for endpoints
that declare no `response_model` are read from the route handler and marked
`(inferred from handler)`. After refreshing `openapi.json`, diff it to see which
paths/schemas changed and re-curate the affected group doc.

## Scope note

This slice intentionally excludes execution/order-routing, options chains, news,
debate, journaling, agents, and other surfaces not used by strategy R\&D. The full
endpoint inventory lives in `openapi.json`.