@ufcalendar/sdk 0.8.5 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -673,6 +673,9 @@ interface CareerBout {
673
673
  time_seconds: number | null;
674
674
  weight_class: string | null;
675
675
  sport: string | null;
676
+ /** UFCalendar fantasy points for this fighter's corner — settled
677
+ * launch-promotion bouts with per-fight totals; null otherwise. */
678
+ fantasy_points: number | null;
676
679
  [k: string]: unknown;
677
680
  }
678
681
  interface RankingEntry {
@@ -1340,6 +1343,105 @@ interface Article {
1340
1343
  /** Delivered language: the translation when one exists, English otherwise. */
1341
1344
  served_locale: ArticleLocale;
1342
1345
  }
1346
+ /** Points per scoring category; a null category scored nothing. */
1347
+ interface FantasyBreakdown {
1348
+ /** Total strikes landed × 0.2. */
1349
+ strikes: number | null;
1350
+ /** Significant strikes landed × 0.2 (on top of the total-strike point). */
1351
+ sig_strikes: number | null;
1352
+ /** Control time × 0.03 per second. */
1353
+ control: number | null;
1354
+ /** Takedowns landed × 5. */
1355
+ takedowns: number | null;
1356
+ /** Reversals × 5. */
1357
+ reversals: number | null;
1358
+ /** Knockdowns × 10. */
1359
+ knockdowns: number | null;
1360
+ /** R1 finish 90 · R2 70 · R3 45 · R4/R5 40 · decision win 30; 0 for a loss, draw, NC or DQ win. */
1361
+ win_bonus: number | null;
1362
+ /** 25 for a finish inside the first 60 s of round 1. */
1363
+ quick_win_bonus: number | null;
1364
+ }
1365
+ /** UFCalendar fantasy points for one corner of one bout. */
1366
+ interface Fantasy {
1367
+ points: number;
1368
+ breakdown: FantasyBreakdown;
1369
+ /** false = a stat is missing or the bout is not settled; `points` is then a floor. */
1370
+ complete: boolean;
1371
+ }
1372
+ /** One corner's per-fight totals (`GET /v1/fights/{id}/stats`). */
1373
+ interface FightStatLine {
1374
+ fighter_id: number;
1375
+ fighter_position: number;
1376
+ corner: 'a' | 'b' | null;
1377
+ knockdowns: number | null;
1378
+ sig_strikes_landed: number | null;
1379
+ sig_strikes_attempted: number | null;
1380
+ total_strikes_landed: number | null;
1381
+ total_strikes_attempted: number | null;
1382
+ takedowns_landed: number | null;
1383
+ takedowns_attempted: number | null;
1384
+ submission_attempts: number | null;
1385
+ reversals: number | null;
1386
+ control_time_sec: number | null;
1387
+ fantasy: Fantasy;
1388
+ [k: string]: unknown;
1389
+ }
1390
+ /** `meta.quality` on `GET /v1/fights/{id}/stats` (read `lastMeta.quality`). */
1391
+ interface StatsQuality {
1392
+ has_totals: boolean;
1393
+ has_rounds: boolean;
1394
+ has_position_data: boolean;
1395
+ /** Round sums of sig strikes / takedowns / knockdowns equal the totals; null with no rounds. */
1396
+ rounds_sum_matches_totals: boolean | null;
1397
+ }
1398
+ interface Referee {
1399
+ /** A slug of the name — spelling variants fold together. */
1400
+ slug: string;
1401
+ name: string;
1402
+ bouts: number;
1403
+ orgs: string[];
1404
+ by_org: Array<{
1405
+ org: string;
1406
+ bouts: number;
1407
+ }>;
1408
+ first_bout: string | null;
1409
+ last_bout: string | null;
1410
+ /** (KO/TKO + submission) / bouts, 0–1. */
1411
+ finish_rate: number | null;
1412
+ methods: {
1413
+ ko_tko: number;
1414
+ submission: number;
1415
+ decision: number;
1416
+ other: number;
1417
+ };
1418
+ avg_fight_time_sec: number | null;
1419
+ }
1420
+ /** One row of `GET /v1/referees/{slug}/fights`: a bout plus its event. */
1421
+ type RefereeFightRow = FightSearchRow;
1422
+ interface CoverageCounts {
1423
+ events: number;
1424
+ fights_completed: number;
1425
+ fights_with_stats: number;
1426
+ fights_with_rounds: number;
1427
+ fights_with_scorecards: number;
1428
+ fights_with_odds: number;
1429
+ stats_rate: number | null;
1430
+ rounds_rate: number | null;
1431
+ scorecards_rate: number | null;
1432
+ odds_rate: number | null;
1433
+ }
1434
+ interface CoverageYear extends CoverageCounts {
1435
+ year: number;
1436
+ }
1437
+ /** One promotion's row of `GET /v1/coverage`. */
1438
+ interface OrgCoverage {
1439
+ org: string;
1440
+ last_result_at: string | null;
1441
+ totals: CoverageCounts;
1442
+ /** Newest first. */
1443
+ years: CoverageYear[];
1444
+ }
1343
1445
 
1344
1446
  declare const DEFAULT_BASE_URL = "https://api.ufcalendar.com/v1";
1345
1447
  /** Default number of times a GET that hit the per-minute limit is retried. */
@@ -1507,8 +1609,12 @@ declare class FightAPI {
1507
1609
  to?: string;
1508
1610
  limit?: number;
1509
1611
  }): AsyncGenerator<OddsHistoryPoint, void, void>;
1510
- /** Per-fight totals for both corners. */
1511
- fightStats(fightId: number | string): Promise<Record<string, unknown>[]>;
1612
+ /**
1613
+ * Per-fight totals for both corners, each with `fantasy` — UFCalendar
1614
+ * fantasy points with a per-category breakdown and `complete`. The
1615
+ * data-quality flags ride in `lastMeta.quality` (`StatsQuality`).
1616
+ */
1617
+ fightStats(fightId: number | string): Promise<FightStatLine[]>;
1512
1618
  /** Round-by-round stat lines for both corners. */
1513
1619
  fightRounds(fightId: number | string): Promise<Record<string, unknown>[]>;
1514
1620
  /**
@@ -1572,6 +1678,30 @@ declare class FightAPI {
1572
1678
  judgeScorecards(judgeId: number | string, opts?: {
1573
1679
  limit?: number;
1574
1680
  }): AsyncGenerator<JudgeScorecardRow, void, void>;
1681
+ /**
1682
+ * Every referee who has worked a settled launch-org bout, busiest first:
1683
+ * bouts, promotions, finish rate, method mix and average fight time. The
1684
+ * id is a slug of the name; `q` is accent- and spacing-insensitive.
1685
+ */
1686
+ referees(opts?: {
1687
+ q?: string;
1688
+ org?: string;
1689
+ limit?: number;
1690
+ }): AsyncGenerator<Referee, void, void>;
1691
+ /** One referee's career aggregates, e.g. `referee('herb-dean')`. */
1692
+ referee(slug: string): Promise<Referee>;
1693
+ /** Every settled bout one referee worked, newest first (the bout plus its `event`). */
1694
+ refereeFights(slug: string, opts?: {
1695
+ limit?: number;
1696
+ }): AsyncGenerator<RefereeFightRow, void, void>;
1697
+ /**
1698
+ * What the database holds per launch org per year: events, settled bouts
1699
+ * and how many carry stats, round stats, commission scorecards and a
1700
+ * consensus odds line, with `totals` and `last_result_at`.
1701
+ */
1702
+ coverage(opts?: {
1703
+ org?: string;
1704
+ }): Promise<OrgCoverage[]>;
1575
1705
  fighters(opts?: {
1576
1706
  q?: string;
1577
1707
  org?: string;
@@ -1759,7 +1889,7 @@ declare class FightAPI {
1759
1889
 
1760
1890
  /** Kept in lockstep with package.json and the User-Agent by
1761
1891
  * `apps/api/src/surfaces.test.ts`. Bump all three together. */
1762
- declare const VERSION = "0.8.5";
1892
+ declare const VERSION = "0.9.0";
1763
1893
 
1764
1894
  /**
1765
1895
  * This file was auto-generated by openapi-typescript.
@@ -4086,6 +4216,10 @@ interface paths {
4086
4216
  /**
4087
4217
  * Per-fight totals
4088
4218
  * @description Both corners: knockdowns, significant/total strikes, takedowns, submission attempts, reversals, control time, and target/position splits (head/body/leg, distance/clinch/ground) where the source provides them. Each line carries `corner` (`a` = the bout's `fighter_a`, `b` = `fighter_b`) beside the stored `fighter_position` (1/2). `distance_time_sec`, `clinch_time_sec`, `ground_time_sec` (integers, nullable) are seconds spent at distance / in the clinch / on the ground, and can appear alongside official strike counts on any org (position time is filled in even where the rest of the row comes from the official stats).
4219
+ *
4220
+ * **UFCalendar fantasy points** (`fantasy` on each line): a classic daily-fantasy-style MMA score for that corner — total strikes landed +0.2, significant strikes landed +0.2 (on top), control time +0.03 per second, takedown +5, reversal +5, knockdown +10; win bonus R1 finish +90, R2 finish +70, R3 finish +45, R4/R5 finish +40, decision win +30; quick-win bonus +25 for a finish inside the first 60 seconds of R1. A finish is KO/TKO or submission; a loss, draw, no contest or DQ win earns no bonus. `fantasy.breakdown` gives the points per category; a category the source does not publish is null and scores nothing, and `fantasy.complete` is then false (`points` is a floor, never a guess) — also false until the bout is settled. Reversals are the one exception: only some promotions publish them, so a missing reversal count never makes a line incomplete.
4221
+ *
4222
+ * **Data-quality flags** (`meta.quality`): `has_totals`, `has_rounds`, `has_position_data` (distance/clinch/ground splits or position time), and `rounds_sum_matches_totals` — per corner, do the round sums of significant strikes, takedowns and knockdowns equal the totals (null when there are no rounds or nothing comparable). Filter on it before charting.
4089
4223
  */
4090
4224
  get: {
4091
4225
  parameters: {
@@ -4116,6 +4250,109 @@ interface paths {
4116
4250
  [name: string]: unknown;
4117
4251
  };
4118
4252
  content: {
4253
+ /**
4254
+ * @example {
4255
+ * "data": [
4256
+ * {
4257
+ * "fighter_id": 1665,
4258
+ * "fighter_position": 1,
4259
+ * "knockdowns": 1,
4260
+ * "sig_strikes_landed": 96,
4261
+ * "sig_strikes_attempted": 119,
4262
+ * "total_strikes_landed": 104,
4263
+ * "total_strikes_attempted": 128,
4264
+ * "takedowns_landed": 1,
4265
+ * "takedowns_attempted": 1,
4266
+ * "submission_attempts": 0,
4267
+ * "reversals": 0,
4268
+ * "control_time_sec": 231,
4269
+ * "distance_time_sec": 625,
4270
+ * "clinch_time_sec": 20,
4271
+ * "ground_time_sec": 230,
4272
+ * "head_landed": 70,
4273
+ * "head_attempted": 91,
4274
+ * "body_landed": 16,
4275
+ * "body_attempted": 18,
4276
+ * "leg_landed": 10,
4277
+ * "leg_attempted": 10,
4278
+ * "distance_landed": 54,
4279
+ * "distance_attempted": 70,
4280
+ * "clinch_landed": 2,
4281
+ * "clinch_attempted": 3,
4282
+ * "ground_landed": 40,
4283
+ * "ground_attempted": 46,
4284
+ * "corner": "a",
4285
+ * "fantasy": {
4286
+ * "points": 106.93,
4287
+ * "breakdown": {
4288
+ * "strikes": 20.8,
4289
+ * "sig_strikes": 19.2,
4290
+ * "control": 6.93,
4291
+ * "takedowns": 5,
4292
+ * "reversals": 0,
4293
+ * "knockdowns": 10,
4294
+ * "win_bonus": 45,
4295
+ * "quick_win_bonus": 0
4296
+ * },
4297
+ * "complete": true
4298
+ * }
4299
+ * },
4300
+ * {
4301
+ * "fighter_id": 1946,
4302
+ * "fighter_position": 2,
4303
+ * "knockdowns": 0,
4304
+ * "sig_strikes_landed": 37,
4305
+ * "sig_strikes_attempted": 89,
4306
+ * "total_strikes_landed": 42,
4307
+ * "total_strikes_attempted": 94,
4308
+ * "takedowns_landed": 0,
4309
+ * "takedowns_attempted": 0,
4310
+ * "submission_attempts": 0,
4311
+ * "reversals": 0,
4312
+ * "control_time_sec": 0,
4313
+ * "distance_time_sec": 625,
4314
+ * "clinch_time_sec": 20,
4315
+ * "ground_time_sec": 230,
4316
+ * "head_landed": 24,
4317
+ * "head_attempted": 75,
4318
+ * "body_landed": 7,
4319
+ * "body_attempted": 8,
4320
+ * "leg_landed": 6,
4321
+ * "leg_attempted": 6,
4322
+ * "distance_landed": 32,
4323
+ * "distance_attempted": 83,
4324
+ * "clinch_landed": 4,
4325
+ * "clinch_attempted": 5,
4326
+ * "ground_landed": 1,
4327
+ * "ground_attempted": 1,
4328
+ * "corner": "b",
4329
+ * "fantasy": {
4330
+ * "points": 15.8,
4331
+ * "breakdown": {
4332
+ * "strikes": 8.4,
4333
+ * "sig_strikes": 7.4,
4334
+ * "control": 0,
4335
+ * "takedowns": 0,
4336
+ * "reversals": 0,
4337
+ * "knockdowns": 0,
4338
+ * "win_bonus": 0,
4339
+ * "quick_win_bonus": 0
4340
+ * },
4341
+ * "complete": true
4342
+ * }
4343
+ * }
4344
+ * ],
4345
+ * "meta": {
4346
+ * "fight_id": 60381,
4347
+ * "quality": {
4348
+ * "has_totals": true,
4349
+ * "has_rounds": true,
4350
+ * "has_position_data": true,
4351
+ * "rounds_sum_matches_totals": true
4352
+ * }
4353
+ * }
4354
+ * }
4355
+ */
4119
4356
  "application/json": components["schemas"]["FightStatsResponse"];
4120
4357
  };
4121
4358
  };
@@ -5344,15 +5581,630 @@ interface paths {
5344
5581
  * "split_rate": 0.2011,
5345
5582
  * "lone_dissent_rate": 0.1023
5346
5583
  * },
5347
- * "pagination": {
5348
- * "next_cursor": "eyJpZCI6NX0",
5349
- * "has_more": true,
5350
- * "limit": 25
5351
- * }
5352
- * }
5584
+ * "pagination": {
5585
+ * "next_cursor": "eyJpZCI6NX0",
5586
+ * "has_more": true,
5587
+ * "limit": 25
5588
+ * }
5589
+ * }
5590
+ * }
5591
+ */
5592
+ "application/json": components["schemas"]["JudgesPageResponse"];
5593
+ };
5594
+ };
5595
+ /** @description Not Modified — `If-None-Match` matched the current weak `ETag`. Empty body. */
5596
+ 304: {
5597
+ headers: {
5598
+ [name: string]: unknown;
5599
+ };
5600
+ content?: never;
5601
+ };
5602
+ /** @description Invalid input (`invalid_org`, `invalid_cursor`). */
5603
+ 400: {
5604
+ headers: {
5605
+ [name: string]: unknown;
5606
+ };
5607
+ content: {
5608
+ "application/json": components["schemas"]["Error"];
5609
+ };
5610
+ };
5611
+ /** @description Missing/invalid API key (`unauthorized`). */
5612
+ 401: {
5613
+ headers: {
5614
+ [name: string]: unknown;
5615
+ };
5616
+ content: {
5617
+ "application/json": components["schemas"]["Error"];
5618
+ };
5619
+ };
5620
+ /** @description No plan on the credential (`subscription_required`) — rare: every account with a key is on at least the free plan (1,000 requests/month, no card; keys at https://www.ufcalendar.com/account/api). */
5621
+ 403: {
5622
+ headers: {
5623
+ [name: string]: unknown;
5624
+ };
5625
+ content: {
5626
+ "application/json": components["schemas"]["Error"];
5627
+ };
5628
+ };
5629
+ /** @description Not found (`not_found`; staged-org data 404s until the org is promoted). */
5630
+ 404: {
5631
+ headers: {
5632
+ [name: string]: unknown;
5633
+ };
5634
+ content: {
5635
+ "application/json": components["schemas"]["Error"];
5636
+ };
5637
+ };
5638
+ /** @description Rate limited (`rate_limited`) or monthly quota reached (`quota_exceeded`). Honor `Retry-After`. */
5639
+ 429: {
5640
+ headers: {
5641
+ [name: string]: unknown;
5642
+ };
5643
+ content: {
5644
+ "application/json": components["schemas"]["Error"];
5645
+ };
5646
+ };
5647
+ /** @description Something broke on our side (`internal_error`). It has been logged under the `request_id`. */
5648
+ 500: {
5649
+ headers: {
5650
+ [name: string]: unknown;
5651
+ };
5652
+ content: {
5653
+ "application/json": components["schemas"]["Error"];
5654
+ };
5655
+ };
5656
+ };
5657
+ };
5658
+ put?: never;
5659
+ post?: never;
5660
+ delete?: never;
5661
+ options?: never;
5662
+ head?: never;
5663
+ patch?: never;
5664
+ trace?: never;
5665
+ };
5666
+ "/v1/judges/{id}": {
5667
+ parameters: {
5668
+ query?: never;
5669
+ header?: never;
5670
+ path?: never;
5671
+ cookie?: never;
5672
+ };
5673
+ /**
5674
+ * One judge
5675
+ * @description A single official's career aggregates. Same shape as a directory row.
5676
+ */
5677
+ get: {
5678
+ parameters: {
5679
+ query?: never;
5680
+ header?: never;
5681
+ path: {
5682
+ id: number;
5683
+ };
5684
+ cookie?: never;
5685
+ };
5686
+ requestBody?: never;
5687
+ responses: {
5688
+ /** @description Judge */
5689
+ 200: {
5690
+ headers: {
5691
+ /** @description Weak validator over the body, e.g. `W/"GKrimLo826WBqG27jbNFsW2ZHmA"`. Send it back as `If-None-Match` to get a 304. */
5692
+ ETag?: string;
5693
+ /** @description Always `private, no-cache`. */
5694
+ "Cache-Control"?: string;
5695
+ /** @description Monthly request quota of the plan. */
5696
+ "X-RateLimit-Limit"?: number;
5697
+ /** @description Requests left this month. */
5698
+ "X-RateLimit-Remaining"?: number;
5699
+ /** @description Unix seconds of the monthly reset. */
5700
+ "X-RateLimit-Reset"?: number;
5701
+ /** @description Quote it to support; the same id is in every error body. */
5702
+ "x-request-id"?: string;
5703
+ [name: string]: unknown;
5704
+ };
5705
+ content: {
5706
+ "application/json": components["schemas"]["JudgeResponse"];
5707
+ };
5708
+ };
5709
+ /** @description Not Modified — `If-None-Match` matched the current weak `ETag`. Empty body. */
5710
+ 304: {
5711
+ headers: {
5712
+ [name: string]: unknown;
5713
+ };
5714
+ content?: never;
5715
+ };
5716
+ /** @description Missing/invalid API key (`unauthorized`). */
5717
+ 401: {
5718
+ headers: {
5719
+ [name: string]: unknown;
5720
+ };
5721
+ content: {
5722
+ "application/json": components["schemas"]["Error"];
5723
+ };
5724
+ };
5725
+ /** @description No plan on the credential (`subscription_required`) — rare: every account with a key is on at least the free plan (1,000 requests/month, no card; keys at https://www.ufcalendar.com/account/api). */
5726
+ 403: {
5727
+ headers: {
5728
+ [name: string]: unknown;
5729
+ };
5730
+ content: {
5731
+ "application/json": components["schemas"]["Error"];
5732
+ };
5733
+ };
5734
+ /** @description Not found (`not_found`; staged-org data 404s until the org is promoted). */
5735
+ 404: {
5736
+ headers: {
5737
+ [name: string]: unknown;
5738
+ };
5739
+ content: {
5740
+ "application/json": components["schemas"]["Error"];
5741
+ };
5742
+ };
5743
+ /** @description Rate limited (`rate_limited`) or monthly quota reached (`quota_exceeded`). Honor `Retry-After`. */
5744
+ 429: {
5745
+ headers: {
5746
+ [name: string]: unknown;
5747
+ };
5748
+ content: {
5749
+ "application/json": components["schemas"]["Error"];
5750
+ };
5751
+ };
5752
+ /** @description Something broke on our side (`internal_error`). It has been logged under the `request_id`. */
5753
+ 500: {
5754
+ headers: {
5755
+ [name: string]: unknown;
5756
+ };
5757
+ content: {
5758
+ "application/json": components["schemas"]["Error"];
5759
+ };
5760
+ };
5761
+ };
5762
+ };
5763
+ put?: never;
5764
+ post?: never;
5765
+ delete?: never;
5766
+ options?: never;
5767
+ head?: never;
5768
+ patch?: never;
5769
+ trace?: never;
5770
+ };
5771
+ "/v1/judges/{id}/scorecards": {
5772
+ parameters: {
5773
+ query?: never;
5774
+ header?: never;
5775
+ path?: never;
5776
+ cookie?: never;
5777
+ };
5778
+ /**
5779
+ * Everything a judge has scored
5780
+ * @description This judge's card for every launch-org bout they worked, newest first — the bout, its event, the decision type, and their own card, with where it sat on the panel: `lone_dissent` (three known verdicts and this judge alone differs from both others), `split` (three known verdicts that do not all agree) — both `null` when the panel is not three judges or a verdict is unknown — and `colleagues`, the other judges' totals and verdicts (the full round-by-round panel is on `/v1/fights/{id}/scorecards`). Cursor-paginated.
5781
+ */
5782
+ get: {
5783
+ parameters: {
5784
+ query?: {
5785
+ /** @description Opaque cursor from `meta.pagination.next_cursor`. */
5786
+ cursor?: string;
5787
+ limit?: number;
5788
+ };
5789
+ header?: never;
5790
+ path: {
5791
+ id: number;
5792
+ };
5793
+ cookie?: never;
5794
+ };
5795
+ requestBody?: never;
5796
+ responses: {
5797
+ /** @description Cards, newest first */
5798
+ 200: {
5799
+ headers: {
5800
+ /** @description Weak validator over the body, e.g. `W/"GKrimLo826WBqG27jbNFsW2ZHmA"`. Send it back as `If-None-Match` to get a 304. */
5801
+ ETag?: string;
5802
+ /** @description Always `private, no-cache`. */
5803
+ "Cache-Control"?: string;
5804
+ /** @description Monthly request quota of the plan. */
5805
+ "X-RateLimit-Limit"?: number;
5806
+ /** @description Requests left this month. */
5807
+ "X-RateLimit-Remaining"?: number;
5808
+ /** @description Unix seconds of the monthly reset. */
5809
+ "X-RateLimit-Reset"?: number;
5810
+ /** @description Quote it to support; the same id is in every error body. */
5811
+ "x-request-id"?: string;
5812
+ [name: string]: unknown;
5813
+ };
5814
+ content: {
5815
+ /**
5816
+ * @example {
5817
+ * "data": [
5818
+ * {
5819
+ * "fight_id": 83379,
5820
+ * "event": {
5821
+ * "id": 2507,
5822
+ * "slug": "ufc-fight-night-2026-08-29",
5823
+ * "title": "UFC Fight Night: Nurmagomedov vs Song",
5824
+ * "org": "ufc",
5825
+ * "starts_at": "2026-08-29T07:00:00.000Z"
5826
+ * },
5827
+ * "fighter_a_id": 213,
5828
+ * "fighter_b_id": 1120,
5829
+ * "decision_type": "split",
5830
+ * "card": {
5831
+ * "judge_id": 36,
5832
+ * "judge_name": "Vito Paolillo",
5833
+ * "total_a": 28,
5834
+ * "total_b": 29,
5835
+ * "winner_fighter_id": 1120,
5836
+ * "is_draw": false,
5837
+ * "scores_known": true,
5838
+ * "rounds": [
5839
+ * {
5840
+ * "round": 1,
5841
+ * "a": 9,
5842
+ * "b": 10
5843
+ * }
5844
+ * ]
5845
+ * },
5846
+ * "lone_dissent": false,
5847
+ * "split": true,
5848
+ * "colleagues": [
5849
+ * {
5850
+ * "judge_id": 34,
5851
+ * "judge_name": "Clemens Werner",
5852
+ * "total_a": 29,
5853
+ * "total_b": 28,
5854
+ * "winner_fighter_id": 213,
5855
+ * "is_draw": false
5856
+ * },
5857
+ * {
5858
+ * "judge_id": 17,
5859
+ * "judge_name": "Cezary Wojciechowski",
5860
+ * "total_a": 28,
5861
+ * "total_b": 29,
5862
+ * "winner_fighter_id": 1120,
5863
+ * "is_draw": false
5864
+ * }
5865
+ * ]
5866
+ * }
5867
+ * ],
5868
+ * "meta": {
5869
+ * "judge": {
5870
+ * "id": 36,
5871
+ * "name": "Vito Paolillo",
5872
+ * "fights": 412,
5873
+ * "rounds_scored": 1290,
5874
+ * "wide_rounds": 40,
5875
+ * "split_fights": 88,
5876
+ * "three_judge_fights": 410,
5877
+ * "lone_dissents": 31,
5878
+ * "first_scored": "2014-05-31",
5879
+ * "last_scored": "2026-08-29",
5880
+ * "orgs": [
5881
+ * "oktagon",
5882
+ * "ufc"
5883
+ * ]
5884
+ * },
5885
+ * "pagination": {
5886
+ * "next_cursor": null,
5887
+ * "has_more": false,
5888
+ * "limit": 25
5889
+ * }
5890
+ * }
5891
+ * }
5892
+ */
5893
+ "application/json": components["schemas"]["JudgeScorecardsResponse"];
5894
+ };
5895
+ };
5896
+ /** @description Not Modified — `If-None-Match` matched the current weak `ETag`. Empty body. */
5897
+ 304: {
5898
+ headers: {
5899
+ [name: string]: unknown;
5900
+ };
5901
+ content?: never;
5902
+ };
5903
+ /** @description Invalid input (`invalid_cursor`). */
5904
+ 400: {
5905
+ headers: {
5906
+ [name: string]: unknown;
5907
+ };
5908
+ content: {
5909
+ "application/json": components["schemas"]["Error"];
5910
+ };
5911
+ };
5912
+ /** @description Missing/invalid API key (`unauthorized`). */
5913
+ 401: {
5914
+ headers: {
5915
+ [name: string]: unknown;
5916
+ };
5917
+ content: {
5918
+ "application/json": components["schemas"]["Error"];
5919
+ };
5920
+ };
5921
+ /** @description No plan on the credential (`subscription_required`) — rare: every account with a key is on at least the free plan (1,000 requests/month, no card; keys at https://www.ufcalendar.com/account/api). */
5922
+ 403: {
5923
+ headers: {
5924
+ [name: string]: unknown;
5925
+ };
5926
+ content: {
5927
+ "application/json": components["schemas"]["Error"];
5928
+ };
5929
+ };
5930
+ /** @description Not found (`not_found`; staged-org data 404s until the org is promoted). */
5931
+ 404: {
5932
+ headers: {
5933
+ [name: string]: unknown;
5934
+ };
5935
+ content: {
5936
+ "application/json": components["schemas"]["Error"];
5937
+ };
5938
+ };
5939
+ /** @description Rate limited (`rate_limited`) or monthly quota reached (`quota_exceeded`). Honor `Retry-After`. */
5940
+ 429: {
5941
+ headers: {
5942
+ [name: string]: unknown;
5943
+ };
5944
+ content: {
5945
+ "application/json": components["schemas"]["Error"];
5946
+ };
5947
+ };
5948
+ /** @description Something broke on our side (`internal_error`). It has been logged under the `request_id`. */
5949
+ 500: {
5950
+ headers: {
5951
+ [name: string]: unknown;
5952
+ };
5953
+ content: {
5954
+ "application/json": components["schemas"]["Error"];
5955
+ };
5956
+ };
5957
+ };
5958
+ };
5959
+ put?: never;
5960
+ post?: never;
5961
+ delete?: never;
5962
+ options?: never;
5963
+ head?: never;
5964
+ patch?: never;
5965
+ trace?: never;
5966
+ };
5967
+ "/v1/referees": {
5968
+ parameters: {
5969
+ query?: never;
5970
+ header?: never;
5971
+ path?: never;
5972
+ cookie?: never;
5973
+ };
5974
+ /**
5975
+ * Referee directory
5976
+ * @description Every referee who has worked a settled launch-promotion bout, busiest first, with their career shape: bouts, promotions (`by_org`), first and last bout, `finish_rate` (KO/TKO + submission share), the method breakdown (`methods`: `ko_tko`, `submission`, `decision`, `other` = draws, no contests, disqualifications) and `avg_fight_time_sec` (elapsed time over bouts with a readable final round and clock, at the sport's standard round length).
5977
+ *
5978
+ * The referee is named on the bout record, not in a table of its own, so the id is a **slug of the name** (the site's slug rule): spelling variants fold into one referee, and two officials who share a name share a slug. Filter with `q` (accent- and spacing-insensitive name match) and `org`.
5979
+ */
5980
+ get: {
5981
+ parameters: {
5982
+ query?: {
5983
+ /** @description Name fragment, accent- and spacing-insensitive. */
5984
+ q?: string;
5985
+ /** @description Launch org slug: `ufc`, `pfl`, `oktagon`, `bkfc` or `rizin`. Staged orgs 400 until promoted. */
5986
+ org?: "ufc" | "pfl" | "oktagon" | "bkfc" | "rizin";
5987
+ /** @description Opaque cursor from `meta.pagination.next_cursor`. */
5988
+ cursor?: string;
5989
+ limit?: number;
5990
+ };
5991
+ header?: never;
5992
+ path?: never;
5993
+ cookie?: never;
5994
+ };
5995
+ requestBody?: never;
5996
+ responses: {
5997
+ /** @description Referees page */
5998
+ 200: {
5999
+ headers: {
6000
+ /** @description Weak validator over the body, e.g. `W/"GKrimLo826WBqG27jbNFsW2ZHmA"`. Send it back as `If-None-Match` to get a 304. */
6001
+ ETag?: string;
6002
+ /** @description Always `private, no-cache`. */
6003
+ "Cache-Control"?: string;
6004
+ /** @description Monthly request quota of the plan. */
6005
+ "X-RateLimit-Limit"?: number;
6006
+ /** @description Requests left this month. */
6007
+ "X-RateLimit-Remaining"?: number;
6008
+ /** @description Unix seconds of the monthly reset. */
6009
+ "X-RateLimit-Reset"?: number;
6010
+ /** @description Quote it to support; the same id is in every error body. */
6011
+ "x-request-id"?: string;
6012
+ [name: string]: unknown;
6013
+ };
6014
+ content: {
6015
+ /**
6016
+ * @example {
6017
+ * "data": [
6018
+ * {
6019
+ * "slug": "herb-dean",
6020
+ * "name": "Herb Dean",
6021
+ * "bouts": 1383,
6022
+ * "orgs": [
6023
+ * "pfl",
6024
+ * "ufc"
6025
+ * ],
6026
+ * "by_org": [
6027
+ * {
6028
+ * "org": "ufc",
6029
+ * "bouts": 1373
6030
+ * },
6031
+ * {
6032
+ * "org": "pfl",
6033
+ * "bouts": 10
6034
+ * }
6035
+ * ],
6036
+ * "first_bout": "2004-04-02",
6037
+ * "last_bout": "2026-10-10",
6038
+ * "finish_rate": 0.5633,
6039
+ * "methods": {
6040
+ * "ko_tko": 503,
6041
+ * "submission": 276,
6042
+ * "decision": 581,
6043
+ * "other": 23
6044
+ * },
6045
+ * "avg_fight_time_sec": 642
6046
+ * }
6047
+ * ],
6048
+ * "meta": {
6049
+ * "total": 418,
6050
+ * "pagination": {
6051
+ * "next_cursor": "eyJpZCI6Im1hcmMtZ29kZGFyZCIsInAiOjJ9",
6052
+ * "has_more": true,
6053
+ * "limit": 3
6054
+ * }
6055
+ * }
6056
+ * }
6057
+ */
6058
+ "application/json": components["schemas"]["RefereesPageResponse"];
6059
+ };
6060
+ };
6061
+ /** @description Not Modified — `If-None-Match` matched the current weak `ETag`. Empty body. */
6062
+ 304: {
6063
+ headers: {
6064
+ [name: string]: unknown;
6065
+ };
6066
+ content?: never;
6067
+ };
6068
+ /** @description Invalid input (`invalid_org`, `invalid_cursor`). */
6069
+ 400: {
6070
+ headers: {
6071
+ [name: string]: unknown;
6072
+ };
6073
+ content: {
6074
+ "application/json": components["schemas"]["Error"];
6075
+ };
6076
+ };
6077
+ /** @description Missing/invalid API key (`unauthorized`). */
6078
+ 401: {
6079
+ headers: {
6080
+ [name: string]: unknown;
6081
+ };
6082
+ content: {
6083
+ "application/json": components["schemas"]["Error"];
6084
+ };
6085
+ };
6086
+ /** @description No plan on the credential (`subscription_required`) — rare: every account with a key is on at least the free plan (1,000 requests/month, no card; keys at https://www.ufcalendar.com/account/api). */
6087
+ 403: {
6088
+ headers: {
6089
+ [name: string]: unknown;
6090
+ };
6091
+ content: {
6092
+ "application/json": components["schemas"]["Error"];
6093
+ };
6094
+ };
6095
+ /** @description Not found (`not_found`; staged-org data 404s until the org is promoted). */
6096
+ 404: {
6097
+ headers: {
6098
+ [name: string]: unknown;
6099
+ };
6100
+ content: {
6101
+ "application/json": components["schemas"]["Error"];
6102
+ };
6103
+ };
6104
+ /** @description Rate limited (`rate_limited`) or monthly quota reached (`quota_exceeded`). Honor `Retry-After`. */
6105
+ 429: {
6106
+ headers: {
6107
+ [name: string]: unknown;
6108
+ };
6109
+ content: {
6110
+ "application/json": components["schemas"]["Error"];
6111
+ };
6112
+ };
6113
+ /** @description Something broke on our side (`internal_error`). It has been logged under the `request_id`. */
6114
+ 500: {
6115
+ headers: {
6116
+ [name: string]: unknown;
6117
+ };
6118
+ content: {
6119
+ "application/json": components["schemas"]["Error"];
6120
+ };
6121
+ };
6122
+ };
6123
+ };
6124
+ put?: never;
6125
+ post?: never;
6126
+ delete?: never;
6127
+ options?: never;
6128
+ head?: never;
6129
+ patch?: never;
6130
+ trace?: never;
6131
+ };
6132
+ "/v1/referees/{slug}": {
6133
+ parameters: {
6134
+ query?: never;
6135
+ header?: never;
6136
+ path?: never;
6137
+ cookie?: never;
6138
+ };
6139
+ /**
6140
+ * One referee
6141
+ * @description A single referee's career aggregates by slug (e.g. `herb-dean`). Same shape as a directory row. A spelling that folds to the same slug (`Herb Dean`) resolves too.
6142
+ */
6143
+ get: {
6144
+ parameters: {
6145
+ query?: never;
6146
+ header?: never;
6147
+ path: {
6148
+ /** @description Referee slug from `/v1/referees`. */
6149
+ slug: string;
6150
+ };
6151
+ cookie?: never;
6152
+ };
6153
+ requestBody?: never;
6154
+ responses: {
6155
+ /** @description Referee */
6156
+ 200: {
6157
+ headers: {
6158
+ /** @description Weak validator over the body, e.g. `W/"GKrimLo826WBqG27jbNFsW2ZHmA"`. Send it back as `If-None-Match` to get a 304. */
6159
+ ETag?: string;
6160
+ /** @description Always `private, no-cache`. */
6161
+ "Cache-Control"?: string;
6162
+ /** @description Monthly request quota of the plan. */
6163
+ "X-RateLimit-Limit"?: number;
6164
+ /** @description Requests left this month. */
6165
+ "X-RateLimit-Remaining"?: number;
6166
+ /** @description Unix seconds of the monthly reset. */
6167
+ "X-RateLimit-Reset"?: number;
6168
+ /** @description Quote it to support; the same id is in every error body. */
6169
+ "x-request-id"?: string;
6170
+ [name: string]: unknown;
6171
+ };
6172
+ content: {
6173
+ /**
6174
+ * @example {
6175
+ * "data": {
6176
+ * "slug": "herb-dean",
6177
+ * "name": "Herb Dean",
6178
+ * "bouts": 1383,
6179
+ * "orgs": [
6180
+ * "pfl",
6181
+ * "ufc"
6182
+ * ],
6183
+ * "by_org": [
6184
+ * {
6185
+ * "org": "ufc",
6186
+ * "bouts": 1373
6187
+ * },
6188
+ * {
6189
+ * "org": "pfl",
6190
+ * "bouts": 10
6191
+ * }
6192
+ * ],
6193
+ * "first_bout": "2004-04-02",
6194
+ * "last_bout": "2026-10-10",
6195
+ * "finish_rate": 0.5633,
6196
+ * "methods": {
6197
+ * "ko_tko": 503,
6198
+ * "submission": 276,
6199
+ * "decision": 581,
6200
+ * "other": 23
6201
+ * },
6202
+ * "avg_fight_time_sec": 642
6203
+ * },
6204
+ * "meta": {}
5353
6205
  * }
5354
6206
  */
5355
- "application/json": components["schemas"]["JudgesPageResponse"];
6207
+ "application/json": components["schemas"]["RefereeResponse"];
5356
6208
  };
5357
6209
  };
5358
6210
  /** @description Not Modified — `If-None-Match` matched the current weak `ETag`. Empty body. */
@@ -5362,15 +6214,6 @@ interface paths {
5362
6214
  };
5363
6215
  content?: never;
5364
6216
  };
5365
- /** @description Invalid input (`invalid_org`, `invalid_cursor`). */
5366
- 400: {
5367
- headers: {
5368
- [name: string]: unknown;
5369
- };
5370
- content: {
5371
- "application/json": components["schemas"]["Error"];
5372
- };
5373
- };
5374
6217
  /** @description Missing/invalid API key (`unauthorized`). */
5375
6218
  401: {
5376
6219
  headers: {
@@ -5426,7 +6269,7 @@ interface paths {
5426
6269
  patch?: never;
5427
6270
  trace?: never;
5428
6271
  };
5429
- "/v1/judges/{id}": {
6272
+ "/v1/referees/{slug}/fights": {
5430
6273
  parameters: {
5431
6274
  query?: never;
5432
6275
  header?: never;
@@ -5434,21 +6277,26 @@ interface paths {
5434
6277
  cookie?: never;
5435
6278
  };
5436
6279
  /**
5437
- * One judge
5438
- * @description A single official's career aggregates. Same shape as a directory row.
6280
+ * Bouts a referee worked
6281
+ * @description Every settled launch-promotion bout this referee worked, newest first — the bout (same shape as `/v1/fights/{id}`) with its `event`. `meta.referee` repeats the referee's aggregates. Cursor-paginated (`limit` 1–100, default 25).
5439
6282
  */
5440
6283
  get: {
5441
6284
  parameters: {
5442
- query?: never;
6285
+ query?: {
6286
+ /** @description Opaque cursor from `meta.pagination.next_cursor`. */
6287
+ cursor?: string;
6288
+ limit?: number;
6289
+ };
5443
6290
  header?: never;
5444
6291
  path: {
5445
- id: number;
6292
+ /** @description Referee slug from `/v1/referees`. */
6293
+ slug: string;
5446
6294
  };
5447
6295
  cookie?: never;
5448
6296
  };
5449
6297
  requestBody?: never;
5450
6298
  responses: {
5451
- /** @description Judge */
6299
+ /** @description Bouts, newest first */
5452
6300
  200: {
5453
6301
  headers: {
5454
6302
  /** @description Weak validator over the body, e.g. `W/"GKrimLo826WBqG27jbNFsW2ZHmA"`. Send it back as `If-None-Match` to get a 304. */
@@ -5466,7 +6314,96 @@ interface paths {
5466
6314
  [name: string]: unknown;
5467
6315
  };
5468
6316
  content: {
5469
- "application/json": components["schemas"]["JudgeResponse"];
6317
+ /**
6318
+ * @example {
6319
+ * "data": [
6320
+ * {
6321
+ * "id": 93271,
6322
+ * "ordering": 10,
6323
+ * "card_section": "prelims",
6324
+ * "sport": "mma",
6325
+ * "weight_class": "Heavyweight",
6326
+ * "division_slug": "heavyweight",
6327
+ * "is_title": false,
6328
+ * "is_main": false,
6329
+ * "scheduled_rounds": 3,
6330
+ * "status": "completed",
6331
+ * "fighter_a": {
6332
+ * "id": 343,
6333
+ * "slug": "allen-frye-jr",
6334
+ * "name": "Allen Frye Jr.",
6335
+ * "nickname": "AJ",
6336
+ * "nationality": "United States",
6337
+ * "country_code": "US"
6338
+ * },
6339
+ * "fighter_b": {
6340
+ * "id": 48658,
6341
+ * "slug": "rj-harris",
6342
+ * "name": "RJ Harris",
6343
+ * "nickname": "The Hammer",
6344
+ * "nationality": "United States",
6345
+ * "country_code": "US"
6346
+ * },
6347
+ * "result": {
6348
+ * "winner_fighter_id": 343,
6349
+ * "method": "KO/TKO",
6350
+ * "method_normalized": "ko_tko",
6351
+ * "finish_detail": null,
6352
+ * "round": 1,
6353
+ * "time": "2:59",
6354
+ * "time_seconds": 179,
6355
+ * "details": null
6356
+ * },
6357
+ * "referee": "Herb Dean",
6358
+ * "bonus": null,
6359
+ * "event": {
6360
+ * "id": 3527,
6361
+ * "slug": "ufc-fight-night-2026-10-11",
6362
+ * "title": "UFC Fight Night: Allen vs Duncan",
6363
+ * "org": "ufc",
6364
+ * "starts_at": "2026-10-10T21:00:00.000Z"
6365
+ * }
6366
+ * }
6367
+ * ],
6368
+ * "meta": {
6369
+ * "referee": {
6370
+ * "slug": "herb-dean",
6371
+ * "name": "Herb Dean",
6372
+ * "bouts": 1383,
6373
+ * "orgs": [
6374
+ * "pfl",
6375
+ * "ufc"
6376
+ * ],
6377
+ * "by_org": [
6378
+ * {
6379
+ * "org": "ufc",
6380
+ * "bouts": 1373
6381
+ * },
6382
+ * {
6383
+ * "org": "pfl",
6384
+ * "bouts": 10
6385
+ * }
6386
+ * ],
6387
+ * "first_bout": "2004-04-02",
6388
+ * "last_bout": "2026-10-10",
6389
+ * "finish_rate": 0.5633,
6390
+ * "methods": {
6391
+ * "ko_tko": 503,
6392
+ * "submission": 276,
6393
+ * "decision": 581,
6394
+ * "other": 23
6395
+ * },
6396
+ * "avg_fight_time_sec": 642
6397
+ * },
6398
+ * "pagination": {
6399
+ * "next_cursor": "eyJpZCI6OTMyMDB9",
6400
+ * "has_more": true,
6401
+ * "limit": 2
6402
+ * }
6403
+ * }
6404
+ * }
6405
+ */
6406
+ "application/json": components["schemas"]["RefereeFightsResponse"];
5470
6407
  };
5471
6408
  };
5472
6409
  /** @description Not Modified — `If-None-Match` matched the current weak `ETag`. Empty body. */
@@ -5476,6 +6413,15 @@ interface paths {
5476
6413
  };
5477
6414
  content?: never;
5478
6415
  };
6416
+ /** @description Invalid input (`invalid_cursor`). */
6417
+ 400: {
6418
+ headers: {
6419
+ [name: string]: unknown;
6420
+ };
6421
+ content: {
6422
+ "application/json": components["schemas"]["Error"];
6423
+ };
6424
+ };
5479
6425
  /** @description Missing/invalid API key (`unauthorized`). */
5480
6426
  401: {
5481
6427
  headers: {
@@ -5531,7 +6477,7 @@ interface paths {
5531
6477
  patch?: never;
5532
6478
  trace?: never;
5533
6479
  };
5534
- "/v1/judges/{id}/scorecards": {
6480
+ "/v1/coverage": {
5535
6481
  parameters: {
5536
6482
  query?: never;
5537
6483
  header?: never;
@@ -5539,25 +6485,22 @@ interface paths {
5539
6485
  cookie?: never;
5540
6486
  };
5541
6487
  /**
5542
- * Everything a judge has scored
5543
- * @description This judge's card for every launch-org bout they worked, newest first — the bout, its event, the decision type, and their own card, with where it sat on the panel: `lone_dissent` (three known verdicts and this judge alone differs from both others), `split` (three known verdicts that do not all agree) — both `null` when the panel is not three judges or a verdict is unknown — and `colleagues`, the other judges' totals and verdicts (the full round-by-round panel is on `/v1/fights/{id}/scorecards`). Cursor-paginated.
6488
+ * Data coverage per promotion
6489
+ * @description What the database actually holds, computed from it (refreshed every 30 minutes) rather than quoted from a marketing page: per launch promotion and per UTC year, the non-cancelled `events` that have started, the settled bouts (`fights_completed`: completed or no contest) and how many of them carry per-fight totals (`fights_with_stats`), round-by-round lines (`fights_with_rounds`), at least one official commission scorecard (`fights_with_scorecards` — a finish has no cards, so this tops out at the decision share) and a consensus odds line across the sportsbooks we track (`fights_with_odds`; information only, not betting advice), each with its 0–1 `*_rate`. `totals` sums every year; `last_result_at` is when the promotion's latest result was recorded. Pass `org` for one promotion.
5544
6490
  */
5545
6491
  get: {
5546
6492
  parameters: {
5547
6493
  query?: {
5548
- /** @description Opaque cursor from `meta.pagination.next_cursor`. */
5549
- cursor?: string;
5550
- limit?: number;
6494
+ /** @description Launch org slug: `ufc`, `pfl`, `oktagon`, `bkfc` or `rizin`. Staged orgs 400 until promoted. */
6495
+ org?: "ufc" | "pfl" | "oktagon" | "bkfc" | "rizin";
5551
6496
  };
5552
6497
  header?: never;
5553
- path: {
5554
- id: number;
5555
- };
6498
+ path?: never;
5556
6499
  cookie?: never;
5557
6500
  };
5558
6501
  requestBody?: never;
5559
6502
  responses: {
5560
- /** @description Cards, newest first */
6503
+ /** @description Coverage per promotion */
5561
6504
  200: {
5562
6505
  headers: {
5563
6506
  /** @description Weak validator over the body, e.g. `W/"GKrimLo826WBqG27jbNFsW2ZHmA"`. Send it back as `If-None-Match` to get a 304. */
@@ -5579,81 +6522,58 @@ interface paths {
5579
6522
  * @example {
5580
6523
  * "data": [
5581
6524
  * {
5582
- * "fight_id": 83379,
5583
- * "event": {
5584
- * "id": 2507,
5585
- * "slug": "ufc-fight-night-2026-08-29",
5586
- * "title": "UFC Fight Night: Nurmagomedov vs Song",
5587
- * "org": "ufc",
5588
- * "starts_at": "2026-08-29T07:00:00.000Z"
5589
- * },
5590
- * "fighter_a_id": 213,
5591
- * "fighter_b_id": 1120,
5592
- * "decision_type": "split",
5593
- * "card": {
5594
- * "judge_id": 36,
5595
- * "judge_name": "Vito Paolillo",
5596
- * "total_a": 28,
5597
- * "total_b": 29,
5598
- * "winner_fighter_id": 1120,
5599
- * "is_draw": false,
5600
- * "scores_known": true,
5601
- * "rounds": [
5602
- * {
5603
- * "round": 1,
5604
- * "a": 9,
5605
- * "b": 10
5606
- * }
5607
- * ]
6525
+ * "org": "ufc",
6526
+ * "last_result_at": "2026-10-30T17:46:34.317Z",
6527
+ * "totals": {
6528
+ * "events": 889,
6529
+ * "fights_completed": 9467,
6530
+ * "fights_with_stats": 9441,
6531
+ * "fights_with_rounds": 9396,
6532
+ * "fights_with_scorecards": 4740,
6533
+ * "fights_with_odds": 6326,
6534
+ * "stats_rate": 0.9973,
6535
+ * "rounds_rate": 0.9925,
6536
+ * "scorecards_rate": 0.5007,
6537
+ * "odds_rate": 0.6682
5608
6538
  * },
5609
- * "lone_dissent": false,
5610
- * "split": true,
5611
- * "colleagues": [
6539
+ * "years": [
5612
6540
  * {
5613
- * "judge_id": 34,
5614
- * "judge_name": "Clemens Werner",
5615
- * "total_a": 29,
5616
- * "total_b": 28,
5617
- * "winner_fighter_id": 213,
5618
- * "is_draw": false
6541
+ * "year": 2026,
6542
+ * "events": 48,
6543
+ * "fights_completed": 526,
6544
+ * "fights_with_stats": 526,
6545
+ * "fights_with_rounds": 526,
6546
+ * "fights_with_scorecards": 342,
6547
+ * "fights_with_odds": 487,
6548
+ * "stats_rate": 1,
6549
+ * "rounds_rate": 1,
6550
+ * "scorecards_rate": 0.6502,
6551
+ * "odds_rate": 0.9259
5619
6552
  * },
5620
6553
  * {
5621
- * "judge_id": 17,
5622
- * "judge_name": "Cezary Wojciechowski",
5623
- * "total_a": 28,
5624
- * "total_b": 29,
5625
- * "winner_fighter_id": 1120,
5626
- * "is_draw": false
6554
+ * "year": 2025,
6555
+ * "events": 53,
6556
+ * "fights_completed": 575,
6557
+ * "fights_with_stats": 572,
6558
+ * "fights_with_rounds": 571,
6559
+ * "fights_with_scorecards": 374,
6560
+ * "fights_with_odds": 454,
6561
+ * "stats_rate": 0.9948,
6562
+ * "rounds_rate": 0.993,
6563
+ * "scorecards_rate": 0.6504,
6564
+ * "odds_rate": 0.7896
5627
6565
  * }
5628
6566
  * ]
5629
6567
  * }
5630
6568
  * ],
5631
6569
  * "meta": {
5632
- * "judge": {
5633
- * "id": 36,
5634
- * "name": "Vito Paolillo",
5635
- * "fights": 412,
5636
- * "rounds_scored": 1290,
5637
- * "wide_rounds": 40,
5638
- * "split_fights": 88,
5639
- * "three_judge_fights": 410,
5640
- * "lone_dissents": 31,
5641
- * "first_scored": "2014-05-31",
5642
- * "last_scored": "2026-08-29",
5643
- * "orgs": [
5644
- * "oktagon",
5645
- * "ufc"
5646
- * ]
5647
- * },
5648
- * "pagination": {
5649
- * "next_cursor": null,
5650
- * "has_more": false,
5651
- * "limit": 25
5652
- * }
6570
+ * "org": null,
6571
+ * "computed_at": "2026-10-31T13:09:12.785Z",
6572
+ * "note": "Settled bouts (completed or no contest) of non-cancelled events that have started, by UTC year of the first bell. A bout counts once per column when it has per-fight totals, round-by-round lines, at least one official commission scorecard, or a consensus odds line across the sportsbooks we track (information only, not betting advice). Rates are 0–1 fractions of fights_completed."
5653
6573
  * }
5654
6574
  * }
5655
6575
  */
5656
- "application/json": components["schemas"]["JudgeScorecardsResponse"];
6576
+ "application/json": components["schemas"]["CoverageResponse"];
5657
6577
  };
5658
6578
  };
5659
6579
  /** @description Not Modified — `If-None-Match` matched the current weak `ETag`. Empty body. */
@@ -5663,7 +6583,7 @@ interface paths {
5663
6583
  };
5664
6584
  content?: never;
5665
6585
  };
5666
- /** @description Invalid input (`invalid_cursor`). */
6586
+ /** @description Invalid input (`invalid_org`). */
5667
6587
  400: {
5668
6588
  headers: {
5669
6589
  [name: string]: unknown;
@@ -6204,7 +7124,7 @@ interface paths {
6204
7124
  };
6205
7125
  /**
6206
7126
  * Complete career timeline
6207
- * @description The fighter's FULL multi-promotion career: native tracked bouts (richest data, `source: "native"`) merged with the wider multi-promotion career record (`source: "history"`). Spans every promotion they fought in — not just launch orgs. **Every key is present on every row** (null when unknown), and each row carries `status` (one vocabulary across both sources: `win`, `loss`, `draw`, `no_contest`, `cancelled`, `upcoming`, `unknown`), `method_normalized`, `time_seconds` and an `opponent` object (`{id, slug, name}`, ids only on native rows) beside the raw `result` / `method` / `time` strings. Newest first; `meta.truncated` is true when the history rows hit their 500-row cap. `source_slug` names the publisher: `ufcalendar` on native rows; on history rows an official publisher (`ufc-official`, `wikipedia`, a promotion's `*-official`), else `public-records`.
7127
+ * @description The fighter's FULL multi-promotion career: native tracked bouts (richest data, `source: "native"`) merged with the wider multi-promotion career record (`source: "history"`). Spans every promotion they fought in — not just launch orgs. **Every key is present on every row** (null when unknown), and each row carries `status` (one vocabulary across both sources: `win`, `loss`, `draw`, `no_contest`, `cancelled`, `upcoming`, `unknown`), `method_normalized`, `time_seconds` and an `opponent` object (`{id, slug, name}`, ids only on native rows) beside the raw `result` / `method` / `time` strings. `fantasy_points` is the fighter's UFCalendar fantasy points for that bout (the score `/v1/fights/{id}/stats` breaks down) on settled launch-promotion bouts with per-fight totals, null otherwise. Newest first; `meta.truncated` is true when the history rows hit their 500-row cap. `source_slug` names the publisher: `ufcalendar` on native rows; on history rows an official publisher (`ufc-official`, `wikipedia`, a promotion's `*-official`), else `public-records`.
6208
7128
  */
6209
7129
  get: {
6210
7130
  parameters: {
@@ -6267,7 +7187,8 @@ interface paths {
6267
7187
  * "id": 1946,
6268
7188
  * "slug": "stipe-miocic",
6269
7189
  * "name": "Stipe Miocic"
6270
- * }
7190
+ * },
7191
+ * "fantasy_points": 106.93
6271
7192
  * }
6272
7193
  * ],
6273
7194
  * "meta": {
@@ -10679,7 +11600,7 @@ interface components {
10679
11600
  /** @description The current UFCalendar consensus line, the closing line once the bout is settled (`/v1/fights/{id}?include=odds` only); null when the bout is unpriced. */
10680
11601
  odds?: components["schemas"]["OddsPair"] | null;
10681
11602
  };
10682
- /** @description Per-fight totals for ONE corner. Target/position splits are null where the source does not log them. */
11603
+ /** @description Per-fight totals for ONE corner. Target/position splits are null where the source does not log them. `fantasy` is the corner's UFCalendar fantasy points. */
10683
11604
  FightStatLine: {
10684
11605
  fighter_id: number;
10685
11606
  /** @description Stored corner encoding: 1 = `fighter_a`, 2 = `fighter_b`. Prefer `corner`. */
@@ -10718,6 +11639,45 @@ interface components {
10718
11639
  clinch_attempted: number | null;
10719
11640
  ground_landed: number | null;
10720
11641
  ground_attempted: number | null;
11642
+ fantasy: components["schemas"]["Fantasy"];
11643
+ };
11644
+ /** @description Points per scoring category. A null category scored nothing. */
11645
+ FantasyBreakdown: {
11646
+ /** @description Total strikes landed × 0.2. Null when the source does not publish total strikes. */
11647
+ strikes: number | null;
11648
+ /** @description Significant strikes landed × 0.2 (on top of the total-strike point). */
11649
+ sig_strikes: number | null;
11650
+ /** @description Control time × 0.03 per second. */
11651
+ control: number | null;
11652
+ /** @description Takedowns landed × 5. */
11653
+ takedowns: number | null;
11654
+ /** @description Reversals × 5. */
11655
+ reversals: number | null;
11656
+ /** @description Knockdowns × 10. */
11657
+ knockdowns: number | null;
11658
+ /** @description R1 finish 90 · R2 finish 70 · R3 finish 45 · R4/R5 finish 40 · decision win 30; 0 for a loss, draw, no contest or a win by disqualification. Null when the bout is not settled or a win's method/round cannot be read. */
11659
+ win_bonus: number | null;
11660
+ /** @description 25 for a finish inside the first 60 seconds of round 1, else 0. Null when it cannot be read. */
11661
+ quick_win_bonus: number | null;
11662
+ };
11663
+ /** @description UFCalendar fantasy points for one corner of one bout — a classic daily-fantasy-style MMA score: total strikes landed +0.2, significant strikes landed +0.2, control +0.03/s, takedown +5, reversal +5, knockdown +10; win bonus R1 finish +90, R2 +70, R3 +45, R4/R5 +40, decision +30; quick win (finish in the first 60 s of R1) +25. No bonus for a loss, draw, no contest or DQ win. */
11664
+ Fantasy: {
11665
+ /** @description Sum of the breakdown (2 decimals). */
11666
+ points: number;
11667
+ breakdown: components["schemas"]["FantasyBreakdown"];
11668
+ /** @description false when a category is null (the source does not publish that stat, the bout is not settled, or the result cannot be read) — `points` is then a floor, never a guess. Reversals are the exception: only some promotions publish them, so a null `reversals` never makes the line incomplete. */
11669
+ complete: boolean;
11670
+ };
11671
+ /** @description Data-quality flags for one bout's statistics — read before charting. */
11672
+ StatsQuality: {
11673
+ /** @description Per-fight totals exist (`data` is non-empty). */
11674
+ has_totals: boolean;
11675
+ /** @description Round-by-round lines exist (`/v1/fights/{id}/rounds`). */
11676
+ has_rounds: boolean;
11677
+ /** @description Distance/clinch/ground strike splits or position time are present on the totals. */
11678
+ has_position_data: boolean;
11679
+ /** @description Per corner, the round sums of significant strikes, takedowns and knockdowns equal the totals (compared only where the total and every round carry the stat). Null when there are no rounds or nothing comparable. */
11680
+ rounds_sum_matches_totals: boolean | null;
10721
11681
  };
10722
11682
  /** @description One corner's line for one round. */
10723
11683
  RoundStatLine: {
@@ -10916,6 +11876,105 @@ interface components {
10916
11876
  /** @description Cards that disagree with the official result. */
10917
11877
  dissenting_judges: components["schemas"]["DissentingJudge"][];
10918
11878
  };
11879
+ /** @description How the bouts this referee worked ended. */
11880
+ RefereeMethods: {
11881
+ ko_tko: number;
11882
+ submission: number;
11883
+ decision: number;
11884
+ /** @description Draws, no contests, disqualifications and unreadable methods. */
11885
+ other: number;
11886
+ };
11887
+ RefereeOrgCount: {
11888
+ org: string;
11889
+ bouts: number;
11890
+ };
11891
+ /** @description One referee's career shape across the launch promotions. */
11892
+ Referee: {
11893
+ /** @description Stable id: the name through the site's slug rule, so spelling variants fold together. Two officials who share a name share a slug. */
11894
+ slug: string;
11895
+ /** @description The most-used spelling. */
11896
+ name: string;
11897
+ /** @description Settled launch-promotion bouts refereed. */
11898
+ bouts: number;
11899
+ /** @description Promotion slugs, alphabetical. */
11900
+ orgs: string[];
11901
+ /** @description Bouts per promotion, busiest first. */
11902
+ by_org: components["schemas"]["RefereeOrgCount"][];
11903
+ /**
11904
+ * Format: date
11905
+ * @description UTC date of the first bout's event.
11906
+ */
11907
+ first_bout: string | null;
11908
+ /**
11909
+ * Format: date
11910
+ * @description UTC date of the latest bout's event.
11911
+ */
11912
+ last_bout: string | null;
11913
+ /** @description (KO/TKO + submission) / bouts, 0–1. */
11914
+ finish_rate: number | null;
11915
+ methods: components["schemas"]["RefereeMethods"];
11916
+ /** @description Mean elapsed fight time over bouts with a readable final round and clock, assuming the sport's standard round length (5 min MMA, 2 min bare-knuckle). */
11917
+ avg_fight_time_sec: number | null;
11918
+ };
11919
+ /** @description Counts over settled bouts plus the share of them carrying each dataset. */
11920
+ CoverageCounts: {
11921
+ /** @description Non-cancelled events that have started. */
11922
+ events: number;
11923
+ /** @description Settled bouts (completed or no contest). */
11924
+ fights_completed: number;
11925
+ /** @description Settled bouts with per-fight totals. */
11926
+ fights_with_stats: number;
11927
+ /** @description Settled bouts with round-by-round lines. */
11928
+ fights_with_rounds: number;
11929
+ /** @description Settled bouts with at least one official commission scorecard (a finish has none, so this tops out at the decision share). */
11930
+ fights_with_scorecards: number;
11931
+ /** @description Settled bouts with a consensus odds line across the sportsbooks we track (information only, not betting advice). */
11932
+ fights_with_odds: number;
11933
+ /** @description fights_with_stats / fights_completed, 0–1; null with no settled bouts. */
11934
+ stats_rate: number | null;
11935
+ /** @description fights_with_rounds / fights_completed. */
11936
+ rounds_rate: number | null;
11937
+ /** @description fights_with_scorecards / fights_completed. */
11938
+ scorecards_rate: number | null;
11939
+ /** @description fights_with_odds / fights_completed. */
11940
+ odds_rate: number | null;
11941
+ };
11942
+ CoverageYear: {
11943
+ /** @description UTC year of the first bell. */
11944
+ year: number;
11945
+ /** @description Non-cancelled events that have started. */
11946
+ events: number;
11947
+ /** @description Settled bouts (completed or no contest). */
11948
+ fights_completed: number;
11949
+ /** @description Settled bouts with per-fight totals. */
11950
+ fights_with_stats: number;
11951
+ /** @description Settled bouts with round-by-round lines. */
11952
+ fights_with_rounds: number;
11953
+ /** @description Settled bouts with at least one official commission scorecard (a finish has none, so this tops out at the decision share). */
11954
+ fights_with_scorecards: number;
11955
+ /** @description Settled bouts with a consensus odds line across the sportsbooks we track (information only, not betting advice). */
11956
+ fights_with_odds: number;
11957
+ /** @description fights_with_stats / fights_completed, 0–1; null with no settled bouts. */
11958
+ stats_rate: number | null;
11959
+ /** @description fights_with_rounds / fights_completed. */
11960
+ rounds_rate: number | null;
11961
+ /** @description fights_with_scorecards / fights_completed. */
11962
+ scorecards_rate: number | null;
11963
+ /** @description fights_with_odds / fights_completed. */
11964
+ odds_rate: number | null;
11965
+ };
11966
+ /** @description What the database holds for one promotion. */
11967
+ OrgCoverage: {
11968
+ org: string;
11969
+ /**
11970
+ * Format: date-time
11971
+ * @description When the promotion's latest result was recorded.
11972
+ */
11973
+ last_result_at: string | null;
11974
+ totals: components["schemas"]["CoverageCounts"];
11975
+ /** @description Newest first. */
11976
+ years: components["schemas"]["CoverageYear"][];
11977
+ };
10919
11978
  /** @description Roster-search row: identity only (the bio lives on the detail route). */
10920
11979
  FighterListItem: {
10921
11980
  id: number;
@@ -11367,6 +12426,8 @@ interface components {
11367
12426
  competition_level: string | null;
11368
12427
  /** @description Who published the row: `ufcalendar` for native bouts; on history rows an official publisher's slug (`ufc-official`, `wikipedia`, a promotion's `*-official`), else `public-records`. */
11369
12428
  source_slug: string | null;
12429
+ /** @description UFCalendar fantasy points for this fighter's corner (same score as `fantasy.points` on `/v1/fights/{id}/stats`). Set on settled launch-promotion bouts with per-fight totals, on `/v1/fighters/{idOrSlug}/history` and the timeline `/v1/compare` reads; null otherwise. */
12430
+ fantasy_points: number | null;
11370
12431
  };
11371
12432
  FighterRankingRow: {
11372
12433
  org: string;
@@ -12621,11 +13682,12 @@ interface components {
12621
13682
  ignored_params?: string[];
12622
13683
  };
12623
13684
  };
12624
- /** @description One line per corner (`corner` a then b). Empty when the source has no totals. */
13685
+ /** @description One line per corner (`corner` a then b), each with its `fantasy` points. Empty when the source has no totals. */
12625
13686
  FightStatsResponse: {
12626
13687
  data: components["schemas"]["FightStatLine"][];
12627
13688
  meta: {
12628
13689
  fight_id: number;
13690
+ quality: components["schemas"]["StatsQuality"];
12629
13691
  /** @description Present only when the request carried query parameters this endpoint does not take — they were ignored. Same list as the `X-UFCalendar-Ignored-Params` header. Sorted, unique. */
12630
13692
  ignored_params?: string[];
12631
13693
  };
@@ -12673,6 +13735,48 @@ interface components {
12673
13735
  ignored_params?: string[];
12674
13736
  };
12675
13737
  };
13738
+ /** @description Busiest first. */
13739
+ RefereesPageResponse: {
13740
+ data: components["schemas"]["Referee"][];
13741
+ meta: {
13742
+ /** @description Referees matching the filters. */
13743
+ total: number;
13744
+ pagination: components["schemas"]["Pagination"];
13745
+ /** @description Present only when the request carried query parameters this endpoint does not take — they were ignored. Same list as the `X-UFCalendar-Ignored-Params` header. Sorted, unique. */
13746
+ ignored_params?: string[];
13747
+ };
13748
+ };
13749
+ RefereeResponse: {
13750
+ data: components["schemas"]["Referee"];
13751
+ meta: components["schemas"]["EmptyMeta"];
13752
+ };
13753
+ /** @description Newest first. */
13754
+ RefereeFightsResponse: {
13755
+ data: components["schemas"]["FightDetail"][];
13756
+ meta: {
13757
+ referee: components["schemas"]["Referee"];
13758
+ pagination: components["schemas"]["Pagination"];
13759
+ /** @description Present only when the request carried query parameters this endpoint does not take — they were ignored. Same list as the `X-UFCalendar-Ignored-Params` header. Sorted, unique. */
13760
+ ignored_params?: string[];
13761
+ };
13762
+ };
13763
+ /** @description One row per launch promotion, in the API's org order. */
13764
+ CoverageResponse: {
13765
+ data: components["schemas"]["OrgCoverage"][];
13766
+ meta: {
13767
+ /** @description The `org=` filter applied; null for every launch promotion. */
13768
+ org: string | null;
13769
+ /**
13770
+ * Format: date-time
13771
+ * @description When the counts were computed (refreshed every 30 minutes).
13772
+ */
13773
+ computed_at: string;
13774
+ /** @description Always present: what is counted. */
13775
+ note: string;
13776
+ /** @description Present only when the request carried query parameters this endpoint does not take — they were ignored. Same list as the `X-UFCalendar-Ignored-Params` header. Sorted, unique. */
13777
+ ignored_params?: string[];
13778
+ };
13779
+ };
12676
13780
  FightersPageResponse: {
12677
13781
  data: components["schemas"]["FighterListItem"][];
12678
13782
  meta: {
@@ -12977,4 +14081,4 @@ interface components {
12977
14081
  }
12978
14082
  type operations = Record<string, never>;
12979
14083
 
12980
- export { type Article, type ArticleLocale, type ArticleSummary, type BonusAward, type BonusLedger, type Broadcast, type BroadcastRight, type CareerBout, type CareerStats, type Champion, type ChangeFeedEntry, type ChangeKind, type Compare, type CompareAggregates, type CompareBout, type CredentialConfidence, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, type DissentingJudge, type Envelope, type EventChange, type EventDetail, type EventHeadline, type EventInclude, type EventListInclude, type EventOdds, type EventOddsRow, type EventPickem, type EventRef, type EventStatus, type EventStorylines, type EventSummary, type EventWatch, type Fight, FightAPI, FightAPIError, type FightAPIOptions, type FightInclude, type FightOdds, type FightProps, type FightResult, type FightSearchMethod, type FightSearchRow, type Fighter, type FighterAffiliation, type FighterBout, type FighterCredential, type FighterCredentials, type FighterImage, type FighterInclude, type FighterRef, type FighterSummary, type HeadlineCorner, type Judge, type JudgeColleague, type JudgeLeague, type JudgeScorecardRow, type LeaderboardRow, MAX_RETRY_AFTER_SECONDS, type MatchmakerCorner, type MatchmakerTag, type Matchup, type Meta, type MethodNormalized, type OddsBlock, type OddsHistoryPoint, type OddsLine, type OddsMovement, type OddsPair, type Org, type OrgDivision, type PickemSplit, type Plan, type Plans, type PowerIndex, type PowerIndexFighter, type PowerIndexMover, type PowerIndexRow, type PowerIndexView, type ProbabilitySource, type PropLine, type PropMethodCorner, type PropTotalRounds, type PublicSource, type Query, type QueryValue, type RankingDivision, type RankingEntry, type RankingsBoard, type RateLimit, type RecordBookSection, type RecordEntry, type RightsSeries, type Scorecard, type ScorecardRound, type Scorecards, type SplitDecisionRow, type StatMetric, type StatScope, type StatsPanel, type StorylineCorner, type StorylineTag, type Usage, VERSION, type Venue, type WatchProvider, type WebhookEndpoint, type WhosNext, type YearStats, type operations, type paths };
14084
+ export { type Article, type ArticleLocale, type ArticleSummary, type BonusAward, type BonusLedger, type Broadcast, type BroadcastRight, type CareerBout, type CareerStats, type Champion, type ChangeFeedEntry, type ChangeKind, type Compare, type CompareAggregates, type CompareBout, type CoverageCounts, type CoverageYear, type CredentialConfidence, DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, type DissentingJudge, type Envelope, type EventChange, type EventDetail, type EventHeadline, type EventInclude, type EventListInclude, type EventOdds, type EventOddsRow, type EventPickem, type EventRef, type EventStatus, type EventStorylines, type EventSummary, type EventWatch, type Fantasy, type FantasyBreakdown, type Fight, FightAPI, FightAPIError, type FightAPIOptions, type FightInclude, type FightOdds, type FightProps, type FightResult, type FightSearchMethod, type FightSearchRow, type FightStatLine, type Fighter, type FighterAffiliation, type FighterBout, type FighterCredential, type FighterCredentials, type FighterImage, type FighterInclude, type FighterRef, type FighterSummary, type HeadlineCorner, type Judge, type JudgeColleague, type JudgeLeague, type JudgeScorecardRow, type LeaderboardRow, MAX_RETRY_AFTER_SECONDS, type MatchmakerCorner, type MatchmakerTag, type Matchup, type Meta, type MethodNormalized, type OddsBlock, type OddsHistoryPoint, type OddsLine, type OddsMovement, type OddsPair, type Org, type OrgCoverage, type OrgDivision, type PickemSplit, type Plan, type Plans, type PowerIndex, type PowerIndexFighter, type PowerIndexMover, type PowerIndexRow, type PowerIndexView, type ProbabilitySource, type PropLine, type PropMethodCorner, type PropTotalRounds, type PublicSource, type Query, type QueryValue, type RankingDivision, type RankingEntry, type RankingsBoard, type RateLimit, type RecordBookSection, type RecordEntry, type Referee, type RefereeFightRow, type RightsSeries, type Scorecard, type ScorecardRound, type Scorecards, type SplitDecisionRow, type StatMetric, type StatScope, type StatsPanel, type StatsQuality, type StorylineCorner, type StorylineTag, type Usage, VERSION, type Venue, type WatchProvider, type WebhookEndpoint, type WhosNext, type YearStats, type operations, type paths };