ufcalendar 0.1.0__tar.gz

ufcalendar-0.1.0/.gitignore

@@ -0,0 +1,86 @@
+# Node
+node_modules/
+.pnpm-store/
+.pnpm-debug.log*
+.next/
+.open-next/
+out/
+.vercel/
+*.tsbuildinfo
+apps/web/next-env.d.ts
+# Serwist build output (generated into public/ by `next build`)
+apps/web/public/sw*
+apps/web/public/swe-worker*
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+.uv-cache/
+.pytest_cache/
+
+# Scrapy
+.scrapy/
+
+# Logs (root-only so we don't accidentally swallow source dirs named "logs/")
+*.log
+/logs/
+
+# Env
+.env
+.env.local
+.env.*.local
+!.env.example
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode/
+.idea/
+*.swp
+.claude/
+
+# SEO audit output directories — easy to regenerate via /claude-seo:seo-audit
+seo-audit-*/
+
+# Browser network captures — debug artifacts that can contain auth headers/cookies
+*.har
+
+# Google OAuth secrets — live in ~/.config/ufcalendar/seo-google/, never in the repo
+client_secret*.json
+oauth-token*.json
+
+# AI-search eval runs (results/grades are large and reproducible)
+apps/web/scripts/search-eval/runs/
+
+# Demo-video render artifacts (/demo-video output: frames, webm captures, mp4 exports)
+marketing/
+
+# ML track: the SOURCE is tracked (it builds the prod rescore image — see
+# ml/Dockerfile); only the regenerable bulk is ignored. Blanket-ignoring ml/
+# untracked predict.py/explain_card.py etc., which are load-bearing for the
+# ml-rescore container.
+ml/.venv/
+ml/__pycache__/
+ml/data/
+ml/models/
+# Rendered parlay/pick artifact pages — the JSON record next to them IS the
+# dated experiment log (tracked); the HTML is just a re-renderable view.
+ml/predictions/*.html
+
+# be-writer skill: exemplar library is copyrighted source text — S3 only,
+# fetched on demand (see .claude/skills/be-writer/SKILL.md), never committed.
+.claude/skills/be-writer/exemplars/
+
+# Harvest artifacts (raw scrape output). Durable home is the bronze S3
+# layer; the generated apps/web/lib/fight-dna-data.ts is what's committed.
+scraper/data/
+apps/api/dist/
+
+# Fighter-credentials research corpus: per-fighter JSONs live in S3
+# (s3://ufcalendar-raw-203012547507/fighter-credentials/json/), not git.
+# PROGRESS.md is force-added and stays tracked as the runbook.
+docs/research/fighter-credentials/backfill/*.json

ufcalendar-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UFCalendar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ufcalendar-0.1.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.5
+Name: ufcalendar
+Version: 0.1.0
+Summary: Python client for the UFCalendar Fight API: UFC, PFL, OKTAGON and BKFC events, fight cards, results, per-round stats, fighter careers and UFC rankings history since 2013.
+Project-URL: Homepage, https://www.ufcalendar.com/developers
+Project-URL: Documentation, https://api.ufcalendar.com/docs
+Project-URL: UFC API, https://www.ufcalendar.com/developers/ufc-api
+Project-URL: OpenAPI spec, https://api.ufcalendar.com/openapi.json
+Project-URL: Source, https://github.com/UFCalendar/ufcalendar-python
+Project-URL: Issues, https://github.com/UFCalendar/ufcalendar-python/issues
+Author-email: UFCalendar <api@ufcalendar.com>
+License: MIT
+License-File: LICENSE
+Keywords: api,bkfc,fight-data,mma,mma-api,pfl,rankings,sports-data,ufc,ufc-api
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.28
+Description-Content-Type: text/markdown
+
+# ufcalendar — Python client for the UFCalendar Fight API
+
+The [UFCalendar Fight API](https://www.ufcalendar.com/developers) is a REST API for MMA data: **UFC, PFL, OKTAGON and BKFC** events, full fight cards, results within minutes, per-fight and round-by-round statistics, complete fighter careers, and the only **UFC rankings API with point-in-time history back to 2013**. This package is a thin `requests` wrapper over it — one method per endpoint, cursor pagination handled for you.
+
+```bash
+pip install ufcalendar
+```
+
+Get a key (free 1-day trial, 100 requests, no card) at https://www.ufcalendar.com/account/api?trial=1. Paid plans from $19/month, hard caps, no overage.
+
+## Quickstart
+
+```python
+from ufcalendar import FightAPI
+
+api = FightAPI("ufcalendar_...")            # or export UFCAL_API_KEY=...
+
+# Upcoming UFC schedule, soonest first
+for ev in api.events(org="ufc", limit=5):
+    print(ev["starts_at"], ev["title"], "PPV" if ev["is_ppv"] else "")
+
+# Full card + results of the newest completed UFC event
+latest = next(api.events(org="ufc", status="completed", limit=1))
+card = api.event(latest["slug"])
+for f in card["fights"]:
+    r = f.get("result")
+    if r:
+        print(f["fighter_a"]["name"], "vs", f["fighter_b"]["name"], "->", r["method"], f"R{r['round']} {r['time']}")
+
+# Round-by-round statistics for one bout
+rounds = api.fight_rounds(card["fights"][0]["id"])
+
+# UFC rankings on any date since February 2013 (rank 0 = champion)
+board = api.rankings("ufc", date="2016-11-14")
+lw = next(d for d in board["divisions"] if d["division"] == "lightweight")
+print(board["snapshot_date"], [e["name"] for e in lw["entries"][:5]])
+
+# A fighter's complete multi-promotion career
+history = api.fighter_history("islam-makhachev")
+```
+
+## What's covered
+
+| Method | Endpoint |
+|---|---|
+| `events(org, status, from_date, to_date, order)` | `GET /v1/events` (paginated) |
+| `event(slug)` / `event_changes(slug)` | `GET /v1/events/{slug}` / `…/changes` |
+| `fight(id)` / `fight_stats(id)` / `fight_rounds(id)` | `GET /v1/fights/{id}` / `…/stats` / `…/rounds` |
+| `fighters(q, org, country)` / `fighter(slug)` | `GET /v1/fighters` / `…/{slug}` |
+| `fighter_history` / `fighter_stats` / `fighter_rankings` / `fighter_power_index` | `GET /v1/fighters/{slug}/…` |
+| `rankings(org, date)` / `division_rankings(org, division)` / `champions()` | `GET /v1/rankings/…` / `/v1/champions` |
+| `power_index(org)` / `predictions_upcoming()` | `GET /v1/power-index/{org}` / `/v1/predictions/upcoming` |
+| `broadcast_rights(org, country)` / `venue(id)` / `search(q)` / `usage()` | misc |
+| `create_webhook_endpoint(url, events)` … | `POST /v1/webhook-endpoints` (Pro+) |
+| `calendar_ics_url(org)` | `GET /v1/calendar/{org}.ics` |
+
+Full reference: https://api.ufcalendar.com/docs · OpenAPI 3.1: https://api.ufcalendar.com/openapi.json
+
+## Webhooks instead of polling (Pro and up)
+
+```python
+ep = api.create_webhook_endpoint("https://example.com/hooks/ufcal", ["fight.result", "card.changed"])
+print(ep["secret"])   # shown once; verify X-UFCalendar-Signature with it
+```
+
+## Errors and rate limits
+
+Every error raises `FightAPIError` with `.status`, `.code`, `.message`, `.request_id`. After each call `api.last_rate_limit` holds the `X-RateLimit-*` headers.
+
+## Notes
+
+- No betting odds are served, by design.
+- Fighter `images` are Wikimedia Commons / Creative Commons files: display the `license` and `artist` fields as a credit.
+- Not affiliated with UFC, Zuffa, TKO or any promotion. Terms: https://www.ufcalendar.com/developers/terms
+
+MIT licensed.

ufcalendar-0.1.0/README.md

@@ -0,0 +1,76 @@
+# ufcalendar — Python client for the UFCalendar Fight API
+
+The [UFCalendar Fight API](https://www.ufcalendar.com/developers) is a REST API for MMA data: **UFC, PFL, OKTAGON and BKFC** events, full fight cards, results within minutes, per-fight and round-by-round statistics, complete fighter careers, and the only **UFC rankings API with point-in-time history back to 2013**. This package is a thin `requests` wrapper over it — one method per endpoint, cursor pagination handled for you.
+
+```bash
+pip install ufcalendar
+```
+
+Get a key (free 1-day trial, 100 requests, no card) at https://www.ufcalendar.com/account/api?trial=1. Paid plans from $19/month, hard caps, no overage.
+
+## Quickstart
+
+```python
+from ufcalendar import FightAPI
+
+api = FightAPI("ufcalendar_...")            # or export UFCAL_API_KEY=...
+
+# Upcoming UFC schedule, soonest first
+for ev in api.events(org="ufc", limit=5):
+    print(ev["starts_at"], ev["title"], "PPV" if ev["is_ppv"] else "")
+
+# Full card + results of the newest completed UFC event
+latest = next(api.events(org="ufc", status="completed", limit=1))
+card = api.event(latest["slug"])
+for f in card["fights"]:
+    r = f.get("result")
+    if r:
+        print(f["fighter_a"]["name"], "vs", f["fighter_b"]["name"], "->", r["method"], f"R{r['round']} {r['time']}")
+
+# Round-by-round statistics for one bout
+rounds = api.fight_rounds(card["fights"][0]["id"])
+
+# UFC rankings on any date since February 2013 (rank 0 = champion)
+board = api.rankings("ufc", date="2016-11-14")
+lw = next(d for d in board["divisions"] if d["division"] == "lightweight")
+print(board["snapshot_date"], [e["name"] for e in lw["entries"][:5]])
+
+# A fighter's complete multi-promotion career
+history = api.fighter_history("islam-makhachev")
+```
+
+## What's covered
+
+| Method | Endpoint |
+|---|---|
+| `events(org, status, from_date, to_date, order)` | `GET /v1/events` (paginated) |
+| `event(slug)` / `event_changes(slug)` | `GET /v1/events/{slug}` / `…/changes` |
+| `fight(id)` / `fight_stats(id)` / `fight_rounds(id)` | `GET /v1/fights/{id}` / `…/stats` / `…/rounds` |
+| `fighters(q, org, country)` / `fighter(slug)` | `GET /v1/fighters` / `…/{slug}` |
+| `fighter_history` / `fighter_stats` / `fighter_rankings` / `fighter_power_index` | `GET /v1/fighters/{slug}/…` |
+| `rankings(org, date)` / `division_rankings(org, division)` / `champions()` | `GET /v1/rankings/…` / `/v1/champions` |
+| `power_index(org)` / `predictions_upcoming()` | `GET /v1/power-index/{org}` / `/v1/predictions/upcoming` |
+| `broadcast_rights(org, country)` / `venue(id)` / `search(q)` / `usage()` | misc |
+| `create_webhook_endpoint(url, events)` … | `POST /v1/webhook-endpoints` (Pro+) |
+| `calendar_ics_url(org)` | `GET /v1/calendar/{org}.ics` |
+
+Full reference: https://api.ufcalendar.com/docs · OpenAPI 3.1: https://api.ufcalendar.com/openapi.json
+
+## Webhooks instead of polling (Pro and up)
+
+```python
+ep = api.create_webhook_endpoint("https://example.com/hooks/ufcal", ["fight.result", "card.changed"])
+print(ep["secret"])   # shown once; verify X-UFCalendar-Signature with it
+```
+
+## Errors and rate limits
+
+Every error raises `FightAPIError` with `.status`, `.code`, `.message`, `.request_id`. After each call `api.last_rate_limit` holds the `X-RateLimit-*` headers.
+
+## Notes
+
+- No betting odds are served, by design.
+- Fighter `images` are Wikimedia Commons / Creative Commons files: display the `license` and `artist` fields as a credit.
+- Not affiliated with UFC, Zuffa, TKO or any promotion. Terms: https://www.ufcalendar.com/developers/terms
+
+MIT licensed.

ufcalendar-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ufcalendar"
+version = "0.1.0"
+description = "Python client for the UFCalendar Fight API: UFC, PFL, OKTAGON and BKFC events, fight cards, results, per-round stats, fighter careers and UFC rankings history since 2013."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "UFCalendar", email = "api@ufcalendar.com" }]
+keywords = ["ufc", "mma", "api", "ufc-api", "mma-api", "sports-data", "fight-data", "rankings", "bkfc", "pfl"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Internet :: WWW/HTTP",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["requests>=2.28"]
+
+[project.urls]
+Homepage = "https://www.ufcalendar.com/developers"
+Documentation = "https://api.ufcalendar.com/docs"
+"UFC API" = "https://www.ufcalendar.com/developers/ufc-api"
+"OpenAPI spec" = "https://api.ufcalendar.com/openapi.json"
+Source = "https://github.com/UFCalendar/ufcalendar-python"
+Issues = "https://github.com/UFCalendar/ufcalendar-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["ufcalendar"]
+
+[tool.hatch.build.targets.sdist]
+include = ["ufcalendar", "README.md", "LICENSE", "pyproject.toml", "tests"]

ufcalendar-0.1.0/tests/test_client.py

@@ -0,0 +1,82 @@
+"""Offline tests: the client's request shapes and error handling, no network."""
+
+import json
+
+import pytest
+import requests
+
+from ufcalendar import FightAPI, FightAPIError
+
+
+class _Resp:
+    def __init__(self, status, body, headers=None):
+        self.status_code = status
+        self._body = body
+        self.headers = headers or {}
+        self.text = json.dumps(body)
+
+    def json(self):
+        return self._body
+
+
+class _Session:
+    def __init__(self, responses):
+        self.responses = list(responses)
+        self.calls = []
+
+    def request(self, method, url, **kw):
+        self.calls.append((method, url, kw.get("params"), kw.get("json")))
+        return self.responses.pop(0)
+
+
+def test_requires_key(monkeypatch):
+    monkeypatch.delenv("UFCAL_API_KEY", raising=False)
+    with pytest.raises(ValueError):
+        FightAPI()
+
+
+def test_events_paginates_and_drops_none_params():
+    s = _Session([
+        _Resp(200, {"data": [{"slug": "a"}], "meta": {"pagination": {"next_cursor": "c2"}}}, {"X-RateLimit-Remaining": "99"}),
+        _Resp(200, {"data": [{"slug": "b"}], "meta": {"pagination": {"next_cursor": None}}}),
+    ])
+    api = FightAPI("ufcalendar_test", session=s)
+    rows = list(api.events(org="ufc", status=None))
+    assert [r["slug"] for r in rows] == ["a", "b"]
+    assert s.calls[0][1].endswith("/v1/events")
+    assert s.calls[0][2] == {"org": "ufc", "limit": 100}
+    assert s.calls[1][2]["cursor"] == "c2"
+    assert api.last_rate_limit["remaining"] is None  # last call carried no header
+
+
+def test_rankings_date_param():
+    s = _Session([_Resp(200, {"data": {"snapshot_date": "2016-11-07", "divisions": []}})])
+    api = FightAPI("ufcalendar_test", session=s)
+    board = api.rankings("ufc", date="2016-11-14")
+    assert board["snapshot_date"] == "2016-11-07"
+    assert s.calls[0][1].endswith("/v1/rankings/ufc")
+    assert s.calls[0][2] == {"date": "2016-11-14"}
+
+
+def test_error_envelope():
+    s = _Session([_Resp(403, {"error": {"code": "subscription_required", "message": "no plan", "request_id": "req_1"}})])
+    api = FightAPI("ufcalendar_test", session=s)
+    with pytest.raises(FightAPIError) as ei:
+        api.champions()
+    assert ei.value.status == 403
+    assert ei.value.code == "subscription_required"
+    assert ei.value.request_id == "req_1"
+
+
+def test_webhook_create_body():
+    s = _Session([_Resp(201, {"data": {"id": 1, "secret": "whsec"}})])
+    api = FightAPI("ufcalendar_test", session=s)
+    ep = api.create_webhook_endpoint("https://example.com/h", ["fight.result"])
+    assert ep["secret"] == "whsec"
+    assert s.calls[0][0] == "POST"
+    assert s.calls[0][3] == {"url": "https://example.com/h", "events": ["fight.result"]}
+
+
+def test_ics_url_carries_key():
+    api = FightAPI("ufcalendar_test", session=_Session([]))
+    assert api.calendar_ics_url("ufc") == "https://api.ufcalendar.com/v1/calendar/ufc.ics?key=ufcalendar_test"

ufcalendar-0.1.0/ufcalendar/__init__.py

@@ -0,0 +1,19 @@
+"""ufcalendar — Python client for the UFCalendar Fight API.
+
+    from ufcalendar import FightAPI
+
+    api = FightAPI("ufcalendar_...")            # or UFCAL_API_KEY env var
+    for event in api.events(org="ufc"):          # upcoming UFC cards, soonest first
+        print(event["starts_at"], event["title"])
+
+    board = api.rankings("ufc", date="2016-11-14")   # rankings point-in-time since 2013
+    print(board["snapshot_date"], board["divisions"][0]["entries"][0])
+
+Docs: https://api.ufcalendar.com/docs · pricing + free 1-day trial:
+https://www.ufcalendar.com/developers
+"""
+
+from .client import FightAPI, FightAPIError
+
+__all__ = ["FightAPI", "FightAPIError"]
+__version__ = "0.1.0"

ufcalendar-0.1.0/ufcalendar/client.py

@@ -0,0 +1,264 @@
+"""Thin, dependency-light client for https://api.ufcalendar.com/v1.
+
+Every method returns the parsed ``data`` value of the JSON envelope
+(``{"data": ..., "meta": ...}``); list endpoints are generators that follow
+cursor pagination for you. Errors raise :class:`FightAPIError` carrying the
+API's ``code``, ``message`` and ``request_id`` (quote the request id when
+you write to api@ufcalendar.com).
+
+The API serves no betting odds, by design. Fighter ``images`` are Wikimedia
+Commons / Creative Commons files — the ``license`` and ``artist`` fields you
+receive must be displayed as a credit.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, Iterator, List, Optional, Sequence
+
+import requests
+
+DEFAULT_BASE_URL = "https://api.ufcalendar.com/v1"
+_TIMEOUT = 30
+
+
+class FightAPIError(Exception):
+    """An error response from the Fight API."""
+
+    def __init__(self, status: int, code: str, message: str, request_id: Optional[str] = None):
+        super().__init__(f"{status} {code}: {message}" + (f" (request_id={request_id})" if request_id else ""))
+        self.status = status
+        self.code = code
+        self.message = message
+        self.request_id = request_id
+
+
+class FightAPI:
+    """Client for the UFCalendar Fight API.
+
+    :param api_key: ``ufcalendar_…`` key from https://www.ufcalendar.com/account/api.
+        Falls back to the ``UFCAL_API_KEY`` environment variable.
+    :param base_url: override for testing; defaults to the production ``/v1``.
+    :param session: optional :class:`requests.Session` to reuse connections.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        session: Optional[requests.Session] = None,
+        timeout: float = _TIMEOUT,
+    ):
+        key = api_key or os.environ.get("UFCAL_API_KEY")
+        if not key:
+            raise ValueError(
+                "No API key. Pass api_key=... or set UFCAL_API_KEY. "
+                "Keys (and the free 1-day trial) live at https://www.ufcalendar.com/account/api"
+            )
+        self.api_key = key
+        self.base_url = base_url.rstrip("/")
+        self._session = session or requests.Session()
+        self._timeout = timeout
+        self.last_rate_limit: Dict[str, Optional[str]] = {"limit": None, "remaining": None, "reset": None}
+
+    # ------------------------------------------------------------------ core
+
+    def _request(self, method: str, path: str, params: Optional[Dict[str, Any]] = None, json: Any = None) -> Dict[str, Any]:
+        url = f"{self.base_url}/{path.lstrip('/')}"
+        clean = {k: v for k, v in (params or {}).items() if v is not None}
+        resp = self._session.request(
+            method,
+            url,
+            params=clean,
+            json=json,
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Accept": "application/json",
+                "User-Agent": "ufcalendar-python/0.1.0",
+            },
+            timeout=self._timeout,
+            allow_redirects=True,
+        )
+        self.last_rate_limit = {
+            "limit": resp.headers.get("X-RateLimit-Limit"),
+            "remaining": resp.headers.get("X-RateLimit-Remaining"),
+            "reset": resp.headers.get("X-RateLimit-Reset"),
+        }
+        if resp.status_code == 204:
+            return {}
+        try:
+            body = resp.json()
+        except ValueError:
+            body = {}
+        if resp.status_code >= 400:
+            err = body.get("error") if isinstance(body, dict) else None
+            if isinstance(err, dict):
+                raise FightAPIError(resp.status_code, str(err.get("code", "error")), str(err.get("message", resp.text[:200])), err.get("request_id"))
+            raise FightAPIError(resp.status_code, "http_error", resp.text[:200], resp.headers.get("x-request-id"))
+        return body
+
+    def get(self, path: str, **params: Any) -> Any:
+        """Raw GET returning the ``data`` value. Escape hatch for new endpoints."""
+        return self._request("GET", path, params).get("data")
+
+    def _paginate(self, path: str, params: Dict[str, Any], limit: Optional[int]) -> Iterator[Dict[str, Any]]:
+        params = dict(params)
+        params.setdefault("limit", 100)
+        seen = 0
+        while True:
+            body = self._request("GET", path, params)
+            for row in body.get("data") or []:
+                yield row
+                seen += 1
+                if limit is not None and seen >= limit:
+                    return
+            cursor = ((body.get("meta") or {}).get("pagination") or {}).get("next_cursor")
+            if not cursor:
+                return
+            params["cursor"] = cursor
+
+    # ------------------------------------------------------------------ orgs
+
+    def orgs(self) -> List[Dict[str, Any]]:
+        """Launch orgs with capability flags (stats / rounds / rankings / broadcasts / predictions)."""
+        return self.get("orgs")
+
+    def org(self, slug: str) -> Dict[str, Any]:
+        return self.get(f"orgs/{slug}")
+
+    # ---------------------------------------------------------------- events
+
+    def events(
+        self,
+        org: Optional[str] = None,
+        *,
+        status: Optional[str] = None,
+        from_date: Optional[str] = None,
+        to_date: Optional[str] = None,
+        order: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> Iterator[Dict[str, Any]]:
+        """Schedule + results. Bare call = upcoming calendar, soonest first.
+
+        ``status="completed"`` (or ``order="desc"``) browses the archive newest-first.
+        ``from_date`` / ``to_date`` are ``YYYY-MM-DD``.
+        """
+        return self._paginate(
+            "events",
+            {"org": org, "status": status, "from": from_date, "to": to_date, "order": order},
+            limit,
+        )
+
+    def event(self, id_or_slug: str) -> Dict[str, Any]:
+        """One event with its full fight card, venue and broadcasts."""
+        return self.get(f"events/{id_or_slug}")
+
+    def event_changes(self, id_or_slug: str) -> List[Dict[str, Any]]:
+        """Card-change diff log (fight added/removed, opponent swapped, date moved)."""
+        return self.get(f"events/{id_or_slug}/changes")
+
+    # ---------------------------------------------------------------- fights
+
+    def fight(self, fight_id: int) -> Dict[str, Any]:
+        return self.get(f"fights/{fight_id}")
+
+    def fight_stats(self, fight_id: int) -> List[Dict[str, Any]]:
+        """Per-fight totals for both corners."""
+        return self.get(f"fights/{fight_id}/stats")
+
+    def fight_rounds(self, fight_id: int) -> List[Dict[str, Any]]:
+        """Round-by-round stat lines for both corners."""
+        return self.get(f"fights/{fight_id}/rounds")
+
+    # -------------------------------------------------------------- fighters
+
+    def fighters(
+        self,
+        q: Optional[str] = None,
+        *,
+        org: Optional[str] = None,
+        country: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> Iterator[Dict[str, Any]]:
+        return self._paginate("fighters", {"q": q, "org": org, "country": country}, limit)
+
+    def fighter(self, id_or_slug: str) -> Dict[str, Any]:
+        """Bio, records, career stats, Power Index and CC-licensed images."""
+        return self.get(f"fighters/{id_or_slug}")
+
+    def fighter_history(self, id_or_slug: str) -> List[Dict[str, Any]]:
+        """Complete multi-promotion career timeline."""
+        return self.get(f"fighters/{id_or_slug}/history")
+
+    def fighter_stats(self, id_or_slug: str) -> List[Dict[str, Any]]:
+        """Career statistics per scope (``pro-mma``, ``ufc-only`` …)."""
+        return self.get(f"fighters/{id_or_slug}/stats")
+
+    def fighter_rankings(self, id_or_slug: str) -> List[Dict[str, Any]]:
+        """Every official ranking row the fighter ever held, newest first."""
+        return self.get(f"fighters/{id_or_slug}/rankings")
+
+    def fighter_power_index(self, id_or_slug: str) -> Any:
+        return self.get(f"fighters/{id_or_slug}/power-index")
+
+    # -------------------------------------------------------------- rankings
+
+    def rankings(self, org: str = "ufc", *, date: Optional[str] = None, board: Optional[str] = None) -> Dict[str, Any]:
+        """Official board, point-in-time. ``date="YYYY-MM-DD"`` returns the board
+        valid on that day (UFC history back to 2013; rank 0 = champion)."""
+        return self.get(f"rankings/{org}", date=date, board=board)
+
+    def division_rankings(self, org: str, division: str, *, date: Optional[str] = None) -> Dict[str, Any]:
+        return self.get(f"rankings/{org}/{division}", date=date)
+
+    def champions(self) -> Any:
+        """Current champions across every launch org."""
+        return self.get("champions")
+
+    def power_index(self, org: str = "ufc") -> Any:
+        return self.get(f"power-index/{org}")
+
+    # ----------------------------------------------------------------- misc
+
+    def predictions_upcoming(self) -> Any:
+        """Model win probabilities for upcoming UFC bouts."""
+        return self.get("predictions/upcoming")
+
+    def broadcast_rights(self, org: str = "ufc", *, country: Optional[str] = None) -> List[Dict[str, Any]]:
+        """Who airs the promotion, per ISO-2 country."""
+        return self.get(f"broadcast-rights/{org}", country=country)
+
+    def venue(self, venue_id: int) -> Dict[str, Any]:
+        return self.get(f"venues/{venue_id}")
+
+    def search(self, q: str) -> Any:
+        return self.get("search", q=q)
+
+    def usage(self) -> Dict[str, Any]:
+        """Your key's month-to-date quota usage."""
+        return self.get("usage")
+
+    def calendar_ics_url(self, org: str = "ufc") -> str:
+        """Subscribable ICS feed URL for calendar apps (authenticates via ``?key=``)."""
+        return f"{self.base_url}/calendar/{org}.ics?key={self.api_key}"
+
+    # ------------------------------------------------------------- webhooks
+
+    def webhook_endpoints(self) -> List[Dict[str, Any]]:
+        return self.get("webhook-endpoints")
+
+    def create_webhook_endpoint(self, url: str, events: Optional[Sequence[str]] = None) -> Dict[str, Any]:
+        """Register a signed webhook (Pro and up). ``events`` ⊆
+        ``event.announced``, ``fight.result``, ``card.changed``, ``event.completed``.
+        The signing secret is returned ONCE in the response."""
+        body: Dict[str, Any] = {"url": url}
+        if events:
+            body["events"] = list(events)
+        return self._request("POST", "webhook-endpoints", json=body).get("data")
+
+    def delete_webhook_endpoint(self, endpoint_id: int) -> None:
+        self._request("DELETE", f"webhook-endpoints/{endpoint_id}")
+
+    def rotate_webhook_secret(self, endpoint_id: int) -> Dict[str, Any]:
+        return self._request("POST", f"webhook-endpoints/{endpoint_id}/rotate-secret").get("data")