Avarieux API v1

Every request needs an Authorization: Bearer helm_xxxxx header. Mint keys at /settings once your account is on the Dev tier. Each key is scoped to the user who minted it; you cannot mint a key for someone else’s account.

# 1. Mint a key in Settings → API keys.
# 2. Save it — it's shown once and only once.
# 3. Use it as a Bearer token:
curl -H "Authorization: Bearer helm_xxxxx" \
  https://avarieux.com/api/v1/signals

Keys are stored as SHA-256 hashes; the plaintext is never recoverable. Lose it → mint a new one. Revocation is tombstone (not delete) so the audit trail of which keys existed survives revocation.

Each key carries a per-minute rate limit (default 100/min, configurable up to 300/min at mint time). When you exceed it, the response is HTTP 429 with a Retry-After header. Keep an eye on the X-RateLimit-Remaining header on each successful response.

The Dev tier’s daily tool-call cap (20,000) applies in parallel — every API call counts as one tool call. The cap resets at 00:00 UTC.

All errors are JSON with a stable error code and an optional human message. Common codes:

Returns the calling user’s public-event signals over a recent window — the same factual shape the dashboard ledger renders. Each row is { id, ticker, source, action, timestamp, url, grounded }. No scores, no bands, no grouping rows.

Existing API keys and their scopes keep working unchanged; older endpoint paths permanently redirect here. The response schema is the factual six-field shape above.

curl -H "Authorization: Bearer helm_xxxxx" \
  "https://avarieux.com/api/v1/signals?ticker=NVDA&since=7d&limit=20"

Full signal stream for the calling user, filterable by ticker / kind / window. Deterministic — no LLM in the response path; this is your raw firehose.

curl -H "Authorization: Bearer helm_xxxxx" \
  "https://avarieux.com/api/v1/signals/history?ticker=NVDA&kind=filing&since=30d"

The calling user’s brief history as structured, deterministic signal data. Each row carries the brief’s window, its per-ticker signals and its macro signals. Every signal passes a per-kind allowlist, so which fields are present depends on the kind: SEC filing rows carry their detail, citation URL and reported XBRL figures; price and social rows carry a detail line; news rows carry our own story-count statistic and no headline or article link.

The Markdown body is not served here. It is available in the app and in the morning email, both of which are licensed display surfaces. This one is not: our market-data agreement permits display and email delivery and prohibits redistribution through a machine-readable format, and the synthesis quotes licensed vendor content. Same reason news rows arrive without the headline.

curl -H "Authorization: Bearer helm_xxxxx" \
  "https://avarieux.com/api/v1/briefs?limit=5"

Replays an alert-rule AST against the user’s point-in-time signal ledger. Returns a fire timeline + summary stats. The simulation never sees data that didn’t exist at decision time — strict walk-forward.

Body shape (JSON):

{
  "ast": { ... },
  "scope": "watchlist" | "global" | "ticker",
  "scope_ticker": "NVDA" | null,
  "cooldown_minutes": 60,
  "start": "2025-01-01T00:00:00Z",
  "end":   "2026-01-01T00:00:00Z",
  "step_minutes": 60,
  "signal_lookback_hours": 168,
  "name": "rule label"
}

See the /alerts page for the AST builder and example rule shapes you can copy.

POST-on-event webhooks ship in a post-launch release. The pattern: you register a target URL + a signing secret on your settings page, and we POST a signed JSON envelope every time a new public event lands on a ticker you care about. Until then, the polling pattern against GET /api/v1/signals with an after cursor (see above) covers most real-time-ish use cases at 60s lag.

• All timestamps are ISO 8601 in UTC.
• Money fields are decimal strings (not floats) to avoid IEEE-754 surprises in client-side arithmetic.
• Tickers are upper-case canonical form.
• Pagination is offset-based today (limit/offset query params); cursor-based pagination ships before we hit real volume.
• Every list response carries an as_of ISO timestamp at the top level so you know when the snapshot was taken.

• No trading endpoints. Read-only by design. Order routing is intentionally out of scope — we’re informational tooling, not a broker.
• No price predictions. Signals are observations, not forecasts. The API returns sourced historical facts only; future-state language stays out of every response.
• No scores, bands, or weights. No computed score, confidence band, directional read, or any internal weighting is returned — ever. Each row is the factual shape { id, ticker, source, action, timestamp, url, grounded }. Internal scoring inputs never leave the server.

Questions, bug reports, or feature requests: yash@avarieux.com. Status page coming with the webhooks release.