# EVIO API — Full Reference (LLM-flat) > Single concatenated reference file optimized for LLM ingestion. > Mirrored from the human docs at https://evioinc.com/api/docs/. > Last updated: 2026-05-04. ================================================================================ SECTION 1 — OVERVIEW ================================================================================ EVIO API is a dual-surface, agent-primary financial data platform. The same backend, data, and audit trail serves both: - Agent surface: REST + MCP, machine-discoverable, designed for autonomous decision-making. Optimized for token efficiency and structured reasoning. - Human surface: Mintlify docs, an authenticated dashboard for configuration and governance, and a /playground for debugging. EVIO is in closed alpha. The eight endpoints below return mock JSON in their final response shape so design partners can integrate against a stable contract. Live market-data integration is targeted for Q3 2026 and will be a transparent provider swap — your code does not change. EVIO is publicly traded on the OTC Current tier (OTC: EVIO). The Company files annual and quarterly disclosures and audited financials through OTC Markets' alternative reporting standard. EVIO is NOT an SEC-registered issuer. Colorado corporation; headquartered in Henderson, Nevada. ================================================================================ SECTION 2 — AUTHENTICATION ================================================================================ All API requests require a Bearer API key: Authorization: Bearer evk_live_ Test keys are prefixed evk_test_ and bypass billing while still logging usage. Per-agent keys are recommended over org-wide keys; pause/revoke propagates within 1 second. OAuth is available for human-facing dashboard sign-in only; the API surface itself uses Bearer keys exclusively. ================================================================================ SECTION 3 — RESPONSE ENVELOPE ================================================================================ Every successful (2xx) response includes: { "results": [...], // endpoint-specific result body "_reasoning": [ "Sentence 1.", "Sentence 2." ], "_citations": [ { "step": 0, "source": "...", "locator": "..." } ], "_confidence": { "score": 0.87, "label": "high", "factors": ["..."] }, "_links": [ { "id": "XNAS:AAPL", "endpoints": ["/v1/news/sentiment", "..."] } ], "_meta": { "request_id": "req_01HXY...", "latency_ms": 142, "data_freshness": "mock", "tokens_estimated": 318, "version": "v1" } } `data_freshness` ∈ { "mock", "shadow", "live" } and is driven by the server-side `EVIO_DATA_MODE` env flag. Currently always "mock". Opt-in fields via `?include=alternatives,counterfactual,suggestions`: _alternatives: results that ranked just below _counterfactual: what the result would be if a single key input changed _suggestions: 0-3 follow-up tool calls ================================================================================ SECTION 4 — ERROR ENVELOPE ================================================================================ { "error": { "code": "invalid_ticker_format", "message": "Field 'ticker' must be in MIC:SYMBOL format. Received 'apple'. Try 'XNAS:AAPL'.", "recoverable": true, "retry_after_ms": null, "docs_url": "https://evioinc.com/api/docs/#errors/invalid_ticker_format", "request_id": "req_01HXY...", "hints": [ { "field": "ticker", "action": "transform", "suggestion": "XNAS:AAPL" } ] } } `recoverable: true` means an agent can fix the input and retry; `false` means escalate to a human. `retry_after_ms` is non-null only on rate-limit and transient-failure errors. Common error codes: - invalid_ticker_format - invalid_request_body - agent_budget_exceeded - rate_limit_exceeded - data_freshness_stale - backtest_invalid_strategy - portfolio_invalid_position - internal_error Full catalog: https://evioinc.com/api/docs/#errors ================================================================================ SECTION 5 — ENDPOINTS ================================================================================ -------------------------------------------------------------------------------- 5.1 GET /v1/options/unusual -------------------------------------------------------------------------------- MCP tool: evio_options_unusual Returns the top N tickers with statistically unusual options activity over a lookback window. Each result includes contract details, a volume z-score vs. baseline, an open-interest delta indicating new vs. closing positioning, and a reasoning trace. When to use: user asks about unusual options flow, gamma squeezes, potential accumulation, or wants signal candidates from options data. When NOT to use: - Backtesting a specific options strategy → use evio_backtest_run - Computing portfolio Greeks → use evio_portfolio_risk Parameters (query): ticker string ISO MIC:SYMBOL or comma-separated batch (max 50) lookback string Window: 7d, 14d, 30d, 60d, 90d. Default 30d. limit integer Max results, 1..50. Default 5. fields string Comma-separated field selection. Default slim shape. verbose boolean ?verbose=true returns full payload. Example: GET /v1/options/unusual?ticker=XNAS:AAPL&lookback=30d&limit=5 Result shape per item: ticker, strike, expiration, side, volume, baseline_volume, volume_zscore, open_interest_delta, implied_move_bps, rank -------------------------------------------------------------------------------- 5.2 POST /v1/factor/score -------------------------------------------------------------------------------- MCP tool: evio_factor_score Multi-factor decomposition for a basket of tickers (max 50). Returns factor exposures (value, momentum, quality, low-vol, size) plus a composite score. When to use: ranking a basket on factor exposures, screening for factor tilts, explaining an existing portfolio's factor profile. When NOT to use: - Single-name research → use evio_equity_research - Risk decomposition for an actual portfolio → use evio_portfolio_risk Body: { "tickers": ["XNAS:AAPL", "XNAS:MSFT"], "factors": ["value", "momentum", "quality"], "as_of": "2026-05-01" } Result shape per ticker: ticker, factor_exposures{value, momentum, quality, ...}, composite_score, rank -------------------------------------------------------------------------------- 5.3 POST /v1/backtest/run -------------------------------------------------------------------------------- MCP tools: evio_backtest_run (sync), evio_backtest_run_async (returns job_id) Submit a strategy spec. Returns equity curve, Sharpe ratio, max drawdown, and exposure stats. Three execution modes: - Synchronous (default): respond when done, 60-second hard timeout - Streaming (Accept: text/event-stream): SSE progress events - Async (body field mode: "async" or use evio_backtest_run_async): returns job_id; poll GET /v1/jobs/{id} or subscribe to job.completed webhook Body (minimum): { "name": "60-40 monthly rebalance", "universe": ["XNAS:AAPL", "..."], "rules": { ... }, "start": "2020-01-01", "end": "2025-12-31", "mode": "sync" // or "async" } Result shape: equity_curve[], metrics{sharpe, sortino, max_drawdown, ...}, exposure_stats -------------------------------------------------------------------------------- 5.4 GET /v1/equity/research -------------------------------------------------------------------------------- MCP tool: evio_equity_research Composite equity research package for a single ticker (or batch up to 50). Includes rating, target price, key drivers, comparable set, recent catalysts. Parameters: ticker string Required. horizon string "12m" | "24m". Default 12m. Result shape: ticker, rating, target_price, drivers[], comparable_set[], catalysts[] -------------------------------------------------------------------------------- 5.5 GET /v1/regime/classify -------------------------------------------------------------------------------- MCP tool: evio_regime_classify Macro regime classification: risk-on, risk-off, late-cycle, early-cycle, with confidence and 30-day history. Subscribable via webhook event regime.changed. Parameters: region string "global" | "us" | "eu" | "apac". Default us. history integer Days of history to include. Default 30, max 365. Result shape: current_regime, confidence, drivers[], history[] -------------------------------------------------------------------------------- 5.6 GET /v1/news/sentiment -------------------------------------------------------------------------------- MCP tool: evio_news_sentiment Tone-vs-baseline news sentiment for a ticker over a configurable window. Parameters: ticker string Required. window string "1d" | "7d" | "30d". Default 7d. Result shape: ticker, sentiment_score, baseline, zscore, top_headlines[] -------------------------------------------------------------------------------- 5.7 GET /v1/sec/filing -------------------------------------------------------------------------------- MCP tool: evio_sec_filing SEC filing structured summary keyed by accession number, with diff against the prior filing of the same form type (e.g., 10-Q vs. previous 10-Q). Parameters: accession_number string SEC accession number, e.g. 0000320193-25-000001 diff boolean Default true. Result shape: accession_number, form_type, filer, sections[], diff_vs_prior -------------------------------------------------------------------------------- 5.8 POST /v1/portfolio/risk -------------------------------------------------------------------------------- MCP tool: evio_portfolio_risk Submit a portfolio (positions + weights). Returns 1-day and 10-day VaR, expected shortfall, factor exposures, scenario impacts, and top concentration risks. Body: { "positions": [ { "ticker": "XNAS:AAPL", "weight": 0.10, "qty": 100 }, ... ], "horizon_days": 10, "confidence": 0.95 } Result shape: var{1d, 10d}, expected_shortfall, factor_exposures, scenarios[], concentration ================================================================================ SECTION 6 — PAGINATION & RATE LIMITS ================================================================================ Pagination: cursor-based. ?cursor=opaque_string&limit=50 (max 200) Rate-limit headers (per API key): X-RateLimit-Limit X-RateLimit-Remaining X-RateLimit-Reset Default rate limits: Indie: 60 req/min Studio: 600 req/min Pro: 6,000 req/min Enterprise: custom 429 on exhaustion includes retry_after_ms and resets at X-RateLimit-Reset. ================================================================================ SECTION 7 — WEBHOOKS ================================================================================ Subscribable events: regime.changed agent.budget_warning agent.budget_exceeded job.completed job.failed alert.fired (v1.1 stretch) Delivery contract: - HMAC-SHA256 signature in X-Evio-Signature - Exponential backoff up to 24h, then dead-lettered - Idempotent (event UUID); customer must dedupe - Replay available from /settings/webhooks dashboard ================================================================================ SECTION 8 — MCP SERVER ================================================================================ Endpoint: https://api.evioinc.com/mcp Transports: stdio, HTTP+SSE, Streamable HTTP Tool names (snake_case, evio_ prefix): evio_options_unusual evio_factor_score evio_backtest_run evio_backtest_run_async evio_equity_research evio_regime_classify evio_news_sentiment evio_sec_filing evio_portfolio_risk Authentication: standard MCP authorization context with Bearer evk_* token. Claude Desktop config snippet: { "mcpServers": { "evio": { "url": "https://api.evioinc.com/mcp", "transport": "streamable-http", "headers": { "Authorization": "Bearer evk_test_REPLACE_ME" } } } } ================================================================================ SECTION 9 — DISCOVERY ================================================================================ /.well-known/mcp → MCP server URL, transport list, auth, capabilities /.well-known/openapi → Pointer to current OpenAPI document /.well-known/agent-capabilities → Compact JSON manifest of tools, schemas, examples /llms.txt → Plain-text overview optimized for LLMs /llms-full.txt → This file /api/changelog.html → Public release notes github.com/JpDeSilva17/evio-schemas → OpenAPI YAML, JSON Schemas, MCP manifest, framework exports ================================================================================ SECTION 10 — STATUS & CONTACT ================================================================================ Status: https://status.evioinc.com Email: info@evioinc.com Phone: +1 424-224-5358 HQ: Henderson, NV Ticker: OTC: EVIO This page contains forward-looking statements within the meaning of Section 27A of the Securities Act of 1933 and Section 21E of the Securities Exchange Act of 1934.