---
title: "Matchmaker board"
method: GET
path: "/v1/matchmaker/{org}"
tags: ["Matchmaker"]
---

# Matchmaker board

`GET /v1/matchmaker/{org}`

## Request

- Base URL: `https://api.ufcalendar.com`
- URL: `https://api.ufcalendar.com/v1/matchmaker/{org}`
- Auth: HTTP bearer

UFCalendar's matchmaker for one MMA promotion (`ufc`, `pfl`, `oktagon`, `rizin`; `bkfc` 400s `unsupported_org` — the engine runs on the Power Index, which rates MMA only). Every candidate pair inside a division is scored 0–100 for rank proximity, momentum, competitiveness, readiness and story (rematches, trilogy deciders, eliminators): the promotion's official ladder where one exists plus the strongest active unranked Power Index fighters. UFC pairs are scored by UFCalendar's booking model (a ranker trained on every realized UFC booking), weighted by the stakes term; other promotions use the fitted heuristic. Fighters already booked leave the board, pairs already booked are excluded, and one fighter appears in at most two slips per division.

Without `division` the list is the cross-division top board (at most two slips per division); with it, that division's best pairs. `meta.divisions` lists the promotion's divisions (an unknown one 400s `invalid_division`), `meta.rankings_date` the ladder snapshot used (null when the promotion has no current ladder). Each slip: `key` (`lo-hi` fighter ids), `a` (red corner — the better-credentialed side) and `b` with `rank` (0 = champion, null = unranked), `power_index`, `streak` (signed: +3 = three straight wins) and `booked`; `score`; `win_probability_a` from the two Power Index ratings; `tags` (`title`, `eliminator`, `coinFlip`, `bothStreaking`, `finishers`, `trilogyDecider`, `unfinishedBusiness`, `rematch`, `unrankedGem`, `bounceBack`, `steppingUp`, `bothDue`, `booked`).

Computed WITHOUT the website's style-clash (Fight DNA) factor, so scores can differ slightly from ufcalendar.com. A ranking of fights worth making, not a report of bookings; probabilities are model output for information only. Recomputed at most every 10 minutes.

## Path parameters

- `org` 'ufc' | 'pfl' | 'oktagon' | 'rizin', required

## Query parameters

- `division` string
- `limit` integer

## Response `200`

Matchups, best first

- MatchmakerBoardResponse: Best first.
  - `data` Matchup[], required
    - `key` string, required: `lo-hi` fighter ids.
    - `division` string, required
    - `a` MatchmakerCorner, required
      - `id` integer, required
      - `slug` string, required
      - `name` string, required
      - `nationality` string, nullable, required
      - `rank` integer, nullable, required: Official rank: 0 = champion, null = unranked.
      - `power_index` integer, nullable, required: Rounded Power Index rating; null when unrated.
      - `streak` integer, required: Signed: +3 = three straight wins, -2 = two straight losses.
      - `booked` boolean, required: Already booked against someone else on an upcoming card.
    - `b` MatchmakerCorner, required
      - `id` integer, required
      - `slug` string, required
      - `name` string, required
      - `nationality` string, nullable, required
      - `rank` integer, nullable, required: Official rank: 0 = champion, null = unranked.
      - `power_index` integer, nullable, required: Rounded Power Index rating; null when unrated.
      - `streak` integer, required: Signed: +3 = three straight wins, -2 = two straight losses.
      - `booked` boolean, required: Already booked against someone else on an upcoming card.
    - `score` number, required: 0–100.
    - `win_probability_a` number, required: From the two Power Index ratings.
    - `tags` MatchmakerTag[], required
      - `kind` 'title' | 'eliminator' | 'coinFlip' | 'bothStreaking' | 'finishers' | 'trilogyDecider' | 'unfinishedBusiness' | 'rematch' | 'booked' | 'unrankedGem' | 'bounceBack' | 'steppingUp' | 'bothDue' | 'styleClash', required: Tag vocabulary; `styleClash` never fires on the API (no Fight DNA).
      - `a` integer: `bothStreaking`: corner a's streak.
      - `b` integer: `bothStreaking`: corner b's streak.
      - `pct` integer: `finishers`: average recent finish rate, whole percent.
      - `wins` integer: `trilogyDecider`: wins each.
      - `aWins` integer: `rematch`: a's wins in the series.
      - `bWins` integer: `rematch`: b's wins in the series.
  - `meta` object, required
    - `org` string, required
    - `division` string, nullable, required: The `division=` filter applied.
    - `rankings_date` string, date, nullable, required: The ladder snapshot used; null when the promotion has no current ladder.
    - `divisions` string[], required: The promotion's divisions (the `division=` vocabulary).
    - `note` string, required
    - `ignored_params` string[]: 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.

## Other responses

- `304`: Not Modified — `If-None-Match` matched the current weak `ETag`. Empty body.
- `400`: Invalid input (`unsupported_org`, `invalid_division`).
- `401`: Missing/invalid API key (`unauthorized`).
- `403`: No active plan on the key's account (`subscription_required`) — choose a plan or start the free 1-day trial at https://www.ufcalendar.com/account/api.
- `404`: Not found (`not_found`; staged-org data 404s until the org is promoted).
- `429`: Rate limited (`rate_limited`) or monthly quota reached (`quota_exceeded`). Honor `Retry-After`.
- `500`: Something broke on our side (`internal_error`). It has been logged under the `request_id`.

---

[API](https://skmtc.dev/ufcalendar/apis/ufcalendar-fight-api.md) · [All operations](https://skmtc.dev/ufcalendar/apis/ufcalendar-fight-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ufcalendar/apis/ufcalendar-fight-api/revisions/9623cc8fb70b?raw)