API Reference · v1

API Documentation

The Margin of Insight API returns analyst-quality equity research as structured JSON. Every response includes the same standard envelope — tier, freshness metadata, and markdown content fields.

Base URL: https://marginofinsight.com/api/v1  ·  Coverage: US-listed SEC filers only.

Free tier

$0

No auth. Primer only.

Fundamental

$1.00 per call

API key required.

Full Memo

$2.00 per call

API key required.

Machine-readable spec: openapi.json  ·  Agent description: llms.txt

Authentication

The free tier requires no credentials. Paid endpoints require an API key passed as a Bearer token.

Paid request — API key as Bearer

curl https://marginofinsight.com/api/v1/research/AAPL/fundamental \
  -H "Authorization: Bearer moi_your_api_key_here"

API keys are available when the paid tier launches. Credits are pre-purchased via Stripe with no expiry.

Response Format

Every research response uses the same envelope. Content fields are markdown strings — structured JSON wrapping markdown text, not HTML. 

{
  "ticker":          "V",
  "company":         "Visa",
  "exchange":        "NYSE",
  "report_type":    "primer",         // "primer" | "fundamental" | "memo"
  "tier":           "free",           // "free" | "fundamental" | "full"
  "generated_at":   "2026-04-05T08:06:50Z",
  "coverage_as_of": "2026-Q2",
  "freshness_days": 35,
  "steps_included": [1, 2, 3],
  "data": {
    "overview":           "# Visa Inc. (NYSE: V)\n\n...",
    "financial_snapshot": "## Financial Quality Assessment\n\n...",
    "catalysts":          "## Analyst Debate\n\n..."
  },
  "metadata": {
    "data_sources":                    ["SEC EDGAR XBRL", "earnings transcripts", "Tavily web search"],
    "model":                           "claude-sonnet-4-6",
    "steps_run":                       3,
    "estimated_self_research_cost_usd": 0.50,
    "api_version":                     "v1"
  }
}

Free Endpoints — No Authentication Required

GET /api/v1/research/{ticker}/primer FREE

Returns the company primer — business overview, financial snapshot, and recent catalysts. No authentication required. Use to orient an agent to a company before deciding whether to purchase deeper analysis.

Request

curl https://marginofinsight.com/api/v1/research/V/primer

Fields returned in data

overviewBusiness model, value chain, unit economics, core products/services
financial_snapshotRevenue, margins, EPS, FCF — last 4 quarters; key ratios (P/E, EV/EBITDA)
catalystsEarnings analysis, guidance, analyst debate, recent news

Note: for some research sources, overview may be null when no dedicated overview step exists.

GET /api/v1/coverage FREE

Returns all covered tickers with freshness metadata. Use before making a paid call to verify coverage exists. 

curl https://marginofinsight.com/api/v1/coverage

Response shape

{
  "count": 19,
  "tickers": [
    {
      "ticker":        "AXON",
      "company":       "Axon Enterprise",
      "exchange":      "NASDAQ",
      "sector":        "Technology",
      "covered":       true,
      "last_updated":  "2026-04-10T12:37:58Z",
      "freshness_days": 30
    }
  ],
  "api_version": "v1"
}
GET /api/v1/coverage/{ticker} FREE

Returns coverage metadata for a single ticker — availability, freshness, and which tiers are accessible. 

curl https://marginofinsight.com/api/v1/coverage/V

Response shape

{
  "ticker":          "V",
  "company":         "Visa",
  "exchange":        "NYSE",
  "sector":          "Financials",
  "covered":         true,
  "last_updated":    "2026-04-05T08:06:50Z",
  "coverage_as_of":  "2026-Q2",
  "freshness_days":  35,
  "tiers_available": ["free", "fundamental", "full"],
  "api_version":     "v1"
}
POST /api/v1/coverage/request FREE

Request coverage for a ticker not yet in the universe. Free, no authentication required. Fulfilled in 24–48 hours. Provide an email to be notified when research is ready. 

curl -X POST https://marginofinsight.com/api/v1/coverage/request \
  -H "Content-Type: application/json" \
  -d '{"ticker": "AAPL", "email": "you@example.com"}'

Response — queued

{
  "status":                 "queued",
  "ticker":                 "AAPL",
  "request_id":             "cmp034k620001nbbp...",
  "estimated_ready_hours":  24,
  "notification":           "We'll email you@example.com when research is ready."
}

Paid Endpoints — API Key Required

Paid endpoints require a Bearer token. API keys and Stripe billing launch with Phase 2. To be notified: sign up on the homepage.

GET /api/v1/research/{ticker}/fundamental $1.00

Returns 11-step fundamental analysis. Sufficient for screening agents filtering 20 stocks down to 3–4. Includes all free tier fields plus earnings transcripts, competitive positioning, risk register, balance sheet, and industry context. 

curl https://marginofinsight.com/api/v1/research/V/fundamental \
  -H "Authorization: Bearer moi_your_api_key"

Additional fields in data (beyond primer)

revenue_breakdown earnings_analysis competitive_positioning financial_trends risk_register balance_sheet capital_allocation industry_context
GET /api/v1/research/{ticker}/memo $2.00

Returns the full 19-step investment memo. Equivalent to a sell-side initiation note. An LLM generating this research independently costs $7–9 in API calls and 10–20 minutes. 

curl https://marginofinsight.com/api/v1/research/V/memo \
  -H "Authorization: Bearer moi_your_api_key"

Additional fields beyond fundamental

moat_analysis management_quality dcf_valuation comp_analysis sensitivity_matrix scenarios investment_thesis structured_memo

Error Responses

404 — Ticker not covered

{
  "error":       "not_covered",
  "ticker":      "AAPL",
  "request_url": "POST /api/v1/coverage/request"
}

401 — Missing or invalid API key

{
  "error":   "unauthorized",
  "message": "Valid API key required. Pass as: Authorization: Bearer moi_..."
}

402 — Insufficient credits

{
  "error":     "insufficient_credits",
  "message":   "Balance $0.50, required $1.00",
  "topup_url": "https://marginofinsight.com/account"
}

Account & Credits

Credits are pre-purchased via Stripe. Minimum top-up $10, no expiry. Account endpoints launch with the paid tier.

GET/api/v1/account/balanceCurrent credit balance
GET/api/v1/account/usageUsage history and per-call log
POST/api/v1/account/topupAdd credits via Stripe Checkout