API & MCP Guide

There are three ways to pull posts. Free posts need no key; full paid posts and per-ticker numbers open with a subscriber key. Get or manage keys under Account → API & MCP.

1. MCP — connect an AI assistant

Lets Claude, ChatGPT, Cursor and similar tools read and cite this site directly.

Claude (claude.ai · Claude Desktop)

Settings → Connectors → "Add custom connector" → URL https://aiswingx.com/mcp/pro, header Authorization: Bearer asx_…. Then just ask, e.g. "find the latest SOFI post".

Claude Code · Cursor · others (JSON config)

{
  "mcpServers": {
    "aiswingx": {
      "url": "https://aiswingx.com/mcp/pro",
      "headers": { "Authorization": "Bearer asx_YOUR_KEY" }
    }
  }
}

ChatGPT (developer mode · custom GPT)

Settings → Connectors → add MCP server → URL https://aiswingx.com/mcp (free) or /mcp/pro with the header.

Tools

• about — what the service is (so assistants describe it accurately)
• list_posts — newest posts (filter by ticker, locale, tier)
• get_post — one post (four lines + FAQ + body + metrics)
• search_posts — full-text search
• list_tickers — covered tickers
• get_metrics — quarter-by-quarter numbers per ticker (Pro)
• list_facts — facts as filed (on the free server too): value, period, us-gaap tag, a permanent citation URL and a deep link into the EDGAR document
• get_fact — one fact by accession and tag (free server too)
• list_events — the filing calendar (filter by ticker, category, tone, dates; locale ko|en). Free server: next 30 days, titles/dates/tone only / Pro: all dates plus the verbatim sentence, Korean translation, note and EDGAR link
• get_event — one item (Pro)

2. REST API

GET https://aiswingx.com/api/v1/posts?lang=en          # English articles only
GET https://aiswingx.com/api/v1/metrics/NVDA?lang=en   # English metric names
GET https://aiswingx.com/api/v1/feed?lang=ko           # Korean feed
GET https://aiswingx.com/api/v1/events?lang=en         # events: single-language fields (title, text, note, labels)

GET https://aiswingx.com/api/v1                      # index
GET https://aiswingx.com/api/v1/posts?ticker=SOFI    # list
GET https://aiswingx.com/api/v1/posts/sofi-2026q2    # one post
GET https://aiswingx.com/api/v1/search?q=fair+value
GET https://aiswingx.com/api/v1/tickers
GET https://aiswingx.com/api/v1/metrics/SOFI         # free: one quarter of values; subscriber key: every quarter
GET https://aiswingx.com/api/v1/facts?ticker=NVDA    # facts as filed (open, no key)
GET https://aiswingx.com/api/v1/facts/<accession>/<tag>  # one fact

Authorization: Bearer asx_YOUR_KEY

GET https://aiswingx.com/n/0000730263-26-000027/Assets          # human-readable page (Korean: /ko/n/...)
GET https://aiswingx.com/n/0000730263-26-000027                 # every fact in that filing
GET https://aiswingx.com/api/v1/facts/0000730263-26-000027/Assets   # same data, JSON
GET https://aiswingx.com/api/v1/facts?ticker=THO&tag=Assets&limit=100

Responses are JSON. A post carries four_lines (number, analogy, source, watch_next), body_md, faq, metrics, url, plus a share image image (url, jpg, png, 1200×630, alt) and share (url, text, attribution). The image is the article cover; you may embed it in your app, social posts or reports with attribution. The full-post response (get_post / /api/v1/posts/<slug>) is modular: sections (per heading: heading, md, html; the arithmetic table comes as appendix), glossary, faq, metrics, image and share can each be used on their own or recombined in any order. blocks lists the block names.

curl

curl -H "Authorization: Bearer asx_…" "https://aiswingx.com/api/v1/posts/sofi-2026q2"

Python

import requests
r = requests.get("https://aiswingx.com/api/v1/posts", params={"ticker": "SOFI"},
                 headers={"Authorization": "Bearer asx_…"})
for p in r.json()["items"]:
    print(p["ticker"], p["quarter"], p["four_lines"]["number"], p["url"])

2-1. Assembly guide — one article is ten blocks

The full response (GET /api/v1/posts/<slug> or MCP get_post) does not hand you one lump of text. It hands you blocks. Each block stands on its own: use one, or pick several and put them in any order. Whatever you build, end it with the one-line share.attribution.

Also included: body_md / body_html (whole body), ticker · company · quarter · filing, published_at · updated_at · revisions, and blocks (the list of block names). A paid article fetched without a subscriber key returns locked: true and omits only sections and body_* — title, lead, four lines, image and FAQ remain usable.

Recipe 1 — push notification (title + lead + link)

p = requests.get("https://aiswingx.com/api/v1/posts/mstr-2026q2").json()
push(title=p["title"], body=p["lead"], url=p["share"]["url"], image=p["image"]["url"])

Recipe 2 — social card (image + four lines + attribution)

f = p["four_lines"]
caption = "\n".join([p["title"], "", "1. " + f["number"], "2. " + f["analogy"],
                     "3. " + f["source"], "4. " + f["watch_next"], "", p["share"]["attribution"]])
post_to_social(image_url=p["image"]["jpg"], text=caption, link=p["share"]["url"])

Recipe 3 — research note (only the sections you want)

want = {"Why it matters", "What to watch"}
html = f'<img src="{p["image"]["url"]}" alt="{p["image"]["alt"]}">'
html += f"<h1>{p['title']}</h1><p>{p['lead']}</p>"
for s in p["sections"]:
    if s["heading"] in want:
        html += f"<h2>{s['heading']}</h2>" + s["html"]
html += "<p>" + p["share"]["attribution"] + "</p>"

Recipe 4 — ticker dashboard (metrics only, as a chart)

m = requests.get("https://aiswingx.com/api/v1/metrics/MSTR?locale=en",
                 headers={"Authorization": "Bearer asx_…"}).json()["items"]
series = {}
for row in m:                      # name → [(quarter, value)]
    series.setdefault(row["name"], []).append((row["quarter"], row["value"]))
draw_chart(series["Bitcoin fair value / cost"])   # 2025Q4 116.7 → 2026Q2 77.7

Recipe 5 — republish as is (full text + image)

article_html = f'<img src="{p["image"]["url"]}">' + p["body_html"] + f"<p>{p['share']['attribution']}</p>"
# or Markdown: GET https://aiswingx.com/p/mstr-2026q2.md  (the image is already under the title)

Three rules

• Never change a number. Headline, order and design are yours; values, units and sources are not.
• One attribution line (share.attribution) goes on every combination. White-label (no attribution) is a separate license arrangement.
• Use the image by link or download it. For sharing and embeds use the stable image.link; for caching use the ?v= stamp on the file URL as your key.

2-2. Drop into your news feed — three-minute integration

To stream articles into a news feed, app or CMS you do not need to assemble anything: one feed URL is enough. Items arrive flat, with the names news systems already use (title, summary, content HTML, image, date, categories, attribution).

GET https://aiswingx.com/api/v1/feed?lang=en&limit=20            # JSON (default)
GET https://aiswingx.com/api/v1/feed?lang=en&format=jsonfeed      # JSON Feed 1.1
GET https://aiswingx.com/api/v1/feed?lang=en&format=rss           # RSS 2.0 + content:encoded + media:content
Filters: ticker= · sector= · topic= · importance=3 · since=2026-09-01 (or 7d)
Authorization: Bearer asx_…   → with a license key, paid articles come in full (paywall:false)

One article

GET https://aiswingx.com/api/v1/posts/<slug>/embed.html?lang=en&theme=light&parts=four_lines,body,glossary,faq
→ an <article> HTML fragment, ready to insert.

One script tag (widget)

<script src="https://aiswingx.com/embed.js" data-lang="en" data-ticker="NVDA" data-limit="5" data-theme="light"></script>

Renders the latest article cards (cover, ticker, title, summary, link) in place. Works without a key on the free feed.

Receive on publish (webhook)

Under Account → API & MCP, save a webhook URL on your key; when a new article is published we POST the same JSON as a feed item. Headers: X-AiSwingX-Event: post.published, X-AiSwingX-Signature = HMAC-SHA256(secret, body).

2-3. Filing calendar — dated facts only

Dated items companies wrote in their own 10-Q and 10-K filings, ordered by date: debt maturities and repayment schedules, warrant vesting and expiry, earn-outs, backlog recognition, buyback authorizations, lock-up expiries, dividend record and payment dates, shareholder meetings, litigation and regulatory dates, deal closings, restructuring completion, leadership changes, insider trading plans, lease commencement and expiry, equity vesting, contracts and tax — 21 categories. No estimates or forecasts. Each item carries the filing sentence (text), a Korean translation (text_ko), our note (note_ko/note_en), the EDGAR link (source_url) and the accession number.

Free vs paid

Endpoints

GET https://aiswingx.com/api/v1/events?ticker=NVDA,MRVL&from=2026-10-01&to=2026-12-31&limit=200
GET https://aiswingx.com/api/v1/events?category=debt,warrant&tone=negative
GET https://aiswingx.com/api/v1/events?ticker=NVDA&lang=en          # lang=ko|en: single-language fields (title, text, note, category_label, tone_label, url). Omit for both languages
GET https://aiswingx.com/api/v1/events/123?lang=en              # one item
GET https://aiswingx.com/api/v1/events/upcoming/NVDA?limit=10   # upcoming items for one ticker (for a widget next to your news)
GET https://aiswingx.com/api/v1/events/calendar.ics?ticker=NVDA&lang=en   # iCal feed (paid) — add by URL in Google/Apple/Outlook
GET https://aiswingx.com/api/v1/events/embed.html?ticker=NVDA&limit=8&lang=en&theme=light   # drop-in HTML widget (paid)

Fields

• precision — day is an exact date; month, quarter, year and range mean the filing states a period, given as date_start–date_end. Fiscal periods are converted to real dates using each company's fiscal year end.
• category — debt · warrant · earnout · rpo · buyback · lockup · dividend · meeting · regulatory · litigation · deal · restructuring · leadership · insider · crypto · product · lease · option · contract · tax · other
• tone — positive, negative or neutral: a rule-based label from the item type and sentence keywords. Where the direction is not clear from the sentence — a receivable owed to the company, debt already repaid, a sell-to-cover plan, an authorization rather than an action — we leave it neutral. Not advice (e.g. debt maturity = negative, backlog recognition or dividend = positive, a repaid note = neutral).
• title_ko/title_en — short labels (category and date). The evidence is always text, the verbatim sentence.
• status — auto (extracted) or verified (checked by the desk). Hidden items never appear. outcome records whether the event occurred, from later reports.
• url/url_ko — the item's own page, for sharing and citation.
• tone_note — a fixed sentence explaining what the tone label is; show it when redistributing.
• lang — pass ko or en to get single-language fields: title, note, text (for ko, the Korean translation; if not yet translated, the English original, flagged by text_lang), text_original, category_label, tone_label, url. Use this when dropping items straight into a news screen.

Freshness: new 10-Q and 10-K filings are extracted within minutes of EDGAR acceptance. Items are reviewed daily; anything wrong is hidden and drops out of the API immediately. Keep the attribution when redistributing.

2-4. Filing score — how much the numbers moved

Every filing carries a 0–100 score. It is not a forecast or a trading signal: it measures, through nine rules, how much the reported numbers moved in that filing. Every component comes from the same filing's inline XBRL values and the calendar items we extracted, and each one is returned with the figure behind it.

Components: revenue change 15 · net income change 15 · earnings quality (operating cash / net income) 15 · inventory vs revenue 10 · receivables ratio 10 · debt and equity 10 · auto flags 10 · filing calendar 10 · editorial importance 15 (capped at 100). Labels: 70+ "Large change", 40–69 "Moderate", below 40 "Small change".

GET https://aiswingx.com/api/v1/scores?min=70&ticker=NVDA&limit=50&lang=en
GET https://aiswingx.com/api/v1/posts?min_score=70          # filter articles by score
# the same value appears as filing_score on article and filing responses

Attribution requirement — when redistributing the score, show (1) the 0–100 scale, (2) that it is not a credit rating, investment grade, price target or recommendation, and (3) a link to the methodology (methodology_url). The method, not, methodology_url and disclaimer_url fields are written to be used verbatim.

"filing_score": {
  "score": 68, "label": "Moderate", "scale": "0-100",
  "method": "Rule-based measure of how much the figures reported in this filing moved ...",
  "not": "Not a credit rating, investment grade, price target, recommendation or forecast ...",
  "methodology_url": "https://aiswingx.com/docs#score", "disclaimer_url": "https://aiswingx.com/disclaimer",
  "top_factors": [{"key": "net_income", "label": "Net income change"}, ...],
  "components": [{"key": "cash_quality", "label_en": "Earnings quality", "points": 8, "max": 15,
                  "detail_en": "operating cash flow / net income = 54%"}, ...]   // paid keys only
}

Permitted use — the score, its label and the calendar data are for personal, non-commercial use even where they are visible without payment. Showing them to your customers or readers, or placing them in your own product or reports, requires the License plan (Terms, sections 5 and 7). The usage and license_url fields carry the same statement.

Editorial importance (15 points) is a human judgment; the other 85 are computed mechanically from the filing's figures. The score reflects only the filing at publication time and bears no relation to later market prices. See section 6 of the disclaimer.

2-4-1. Improving — the companies whose numbers got better

Where the filing score asks how far the numbers moved, the improvement score asks which way. It compares figures a company printed in its own 10-Q or 10-K against the prior-year comparatives printed beside them in the same document. No outside estimates, no consensus, no price or volume data.

This is not a price forecast and not investment advice. A company whose figures improved may see its shares fall, and the reverse is equally true.

Components, normalised to 0-100 over whatever the filing provides: revenue 20 · operating income 20 · gross margin 15 · cash from operations 15 · free cash flow 10 · net cash position 10 · receivables ratio 5 · inventory ratio 5. Lines a filing does not provide are dropped from both the earned and the available points.

The trend is the direction of this score, not of a share price. It compares the same company's previous filing and returns one of up (improving) · slow (slowing) · flat (unchanged) · down (weakening) · first (first reading).

GET https://aiswingx.com/api/v1/improving?limit=10
GET https://aiswingx.com/api/v1/improving?ticker=NVDA,AMD&days=400
# Web page: https://aiswingx.com/improving

Response (paid)

{
  "tier": "paid", "count": 10, "free_ranks": 3,
  "basis": "Figures printed in the filing itself and the prior-year comparatives ...",
  "disclaimer": "improve_score measures only how far the figures in a filing improved ...",
  "items": [{
    "rank": 1, "ticker": "MU", "company": "Micron Technology, Inc.",
    "form": "10-Q", "period": "2026Q3", "accession": "0000723125-26-000015",
    "filed_at": "2026-06-24T20:31:02+00:00",
    "improve_score": 94,
    "trend": "up", "trend_label": "Improving, 3 quarters", "trend_streak": 3,
    "why": "Revenue +345.7% year on year",
    "components": [
      {"key": "revenue", "label": "Revenue", "prior_year": 9301000000.0,
       "this_filing": 41456000000.0, "unit": "$",
       "change": "+345.7% year on year", "points": 20.0, "max_points": 20},
      {"key": "gross_margin", "label": "Gross margin", "prior_year": 37.7164,
       "this_filing": 84.5619, "unit": "%",
       "change": "37.7% to 84.6% (+46.8pp)", "points": 15, "max_points": 15}
    ],
    "filing_url": "https://www.sec.gov/Archives/edgar/data/723125/...",
    "article_url": "https://aiswingx.com/p/mu-fy26q3"
  }]
}

Python — keep only the companies still improving

import requests

r = requests.get("https://aiswingx.com/api/v1/improving",
                 params={"limit": 50},
                 headers={"Authorization": "Bearer asx_..."}, timeout=10)
r.raise_for_status()
d = r.json()

for it in d["items"]:
    if it.get("trend") in ("up", "slow") and (it.get("improve_score") or 0) >= 70:
        print(f'{it["rank"]:2d}. {it["ticker"]:6s} {it["improve_score"]:3d}  '
              f'{it["trend_label"]}  {it["why"]}')
        for c in it["components"]:
            if c["points"] > 0:
                print(f'      {c["label"]}: {c["change"]}')
        print("      filing:", it["filing_url"])

# When you redistribute, show these two sentences alongside the figures.
print(d["basis"]); print(d["disclaimer"])

curl

curl -s "https://aiswingx.com/api/v1/improving?limit=10" \
  -H "Authorization: Bearer asx_..." | jq '.items[] | {rank, ticker, improve_score, trend_label, why}'

Attribution — when you redistribute the improvement score, show (1) the 0-100 scale, (2) that it is not a price forecast, investment grade, price target or recommendation, and (3) a link to the methodology. The basis, disclaimer and docs fields carry wording you can use as is. The full notice is in clause 6 of the disclaimer.

Rate limits

Limits apply in two layers — per hour and per day, counted over the last rolling hour and 24 hours. Every response carries the remaining allowance (X-RateLimit-Limit-Hour, X-RateLimit-Remaining-Hour, -Day, X-RateLimit-Tier). Exceeding a limit returns 429 with Retry-After.

HTTP/1.1 200 OK
X-RateLimit-Tier: anonymous
X-RateLimit-Limit-Hour: 20      X-RateLimit-Remaining-Hour: 15
X-RateLimit-Limit-Day: 100      X-RateLimit-Remaining-Day: 84

HTTP/1.1 429 Too Many Requests
Retry-After: 3600
{"error":"rate_limited","tier":"anonymous","exceeded":"hour",
 "limit_per_hour":20,"limit_per_day":100,
 "hint":"Send an API key (Authorization: Bearer asx_...) for higher limits."}

Permitted use: data pulled within these limits on a free or subscriber key is still for personal, non-commercial use (Team: internal use). Redistribution and commercial use require a License key.
MCP calls count against the same limits. If the allowance is tight for your use, tell us through Support in your account.

2-5. Computed metrics — material taken from the filing figures by rule

Alongside the figures written into our articles, /api/v1/metrics/<ticker> carries items computed by a single rule from the XBRL values companies file with EDGAR, for every ticker we cover. They are material, not interpretation: the formula and the source are all there is.

• Non-operating share of pre-tax income (%) = (pre-tax income − operating income) ÷ pre-tax income — the part of the quarter's profit that came from outside operations, such as marks on stakes, interest and currency. Quarters with pre-tax income at or below zero, or under $10m, are left out because the ratio becomes noise; an operating loss pushes the share above 100%, so it is written as 100 with the reason in note.
• Principal due within twelve months ($M) = what the company itself tagged as long-term debt repayable in the next twelve months (LongTermDebtMaturitiesRepaymentsOfPrincipalInNextTwelveMonths). Not our estimate.

The period label comes from the end date of the figure's own period (for example 2026Q2). XBRL fy/fp is the fiscal year of the filing that carried the number, which stamps last year's comparatives as this year's quarter. Neither item is a forecast, and neither implies good or bad. Updated daily.

3. RSS · plain text

• /feed.xml — RSS
• /llms.txt · /llms-full.txt — for AI agents
• Every post at /p/<slug>.md — plain text

Limits & rules

• Personal keys: 200 calls/day · License keys: 5,000/day. Over the limit returns 429.
• Keys are for you (or your license scope). If one leaks, revoke it and issue a new one.
• Cite the article URL and the filing source when quoting. Redistribution in applications or reports requires the License plan. White-label delivery without attribution (white_label=1) works only on keys enabled by the Company under a separate agreement.
• None of this is investment advice.