HTTP API

BYOM & the inference contract

Almanex is the corpus, not the model. Plug in any inference provider — Anthropic, Gemini, OpenAI, or any OpenAI-compatible endpoint (Together, Groq, OpenRouter, vLLM, Ollama). Set one BYOK header to override the managed provider for a single request, or set several to enable cascading fallback (anthropic → gemini → openai → openai-compat).

Keys are read from request headers and forwarded verbatim to the upstream provider. They are never persisted, never logged in full, and never stored anywhere in our infra. BYOK shifts the inference bill off Almanex — _meta.inference_cost_cents comes back as null on those calls.

# Run the comparison agent against a Together-hosted Llama
curl https://almanex.ai/api/agent/compare \
  -H "Authorization: Bearer alm_live_…" \
  -H "X-Model-Endpoint: https://api.together.xyz/v1" \
  -H "X-Model-Key: $TOGETHER_API_KEY" \
  -H "X-Model-Name: meta-llama/Llama-3.3-70B-Instruct-Turbo" \
  -H "Content-Type: application/json" \
  -d '{"tickers":["NVDA","AMD"],"dimension":"growth"}'

Structured error responses

All errors are returned as JSON with a stable error field your code can switch on.

• 401 unauthorized

  { "error": "unauthorized", "reason": "missing|malformed|not_found|revoked", "detail": "…" }

• 429 rate_limited

  { "error": "rate_limited", "plan": "…", "limit": N, "used": N, "remaining": N, "resets_at": <unix> }

• 400 bad_request

  { "error": "bad_request" }

• 404 not_found

  { "error": "not_found" }

Report shape

The full report response (from the slug and /latest endpoints) as a TypeScript-style interface:

interface Report {
  ticker: string;             // "NVDA"
  slug: string;               // "q4-fy26-earnings"
  title: string;
  company: string;
  quarter: string | null;     // "Q4 FY26"
  report_type:                // canonical enum
    | "earnings-update" | "earnings-preview"
    | "initiation" | "thesis"
    | "one-pager" | "comps" | "dcf" | "other";
  rating: string | null;      // "Buy" / "Hold" / "Sell" / null
  price_target: string | null;
  summary: string;
  as_of_date: string;         // ISO date "YYYY-MM-DD"
  generated_at: number;       // unix seconds
  generated_by: string;       // model id
  web_url: string;            // canonical web page
  tags: string[];             // e.g. "sector:information-technology"
  sources: Source[];
  body_md: string;            // markdown
}

interface Source {
  title: string;
  url: string;
  type?: string;              // "earnings-release", "10-K", …
}