# MMA / UFC API
> Live MMA and UFC data as an API — clean JSON, no key. Get the UFC schedule and each event's full fight card (every bout, both fighters, weight class, status and result), browse the official fighter rankings across all 24 divisions (champions and contenders, with rank movement), and open any fighter's profile — nickname, height, weight, reach, stance, fighting style, citizenship, association and their win-loss-draw record by method. Search fighters by name and read the latest UFC news. Live data sourced continuously from ESPN. Distinct combat-sports coverage — ideal for MMA apps, fantasy and betting tools, fan sites, dashboards and Discord bots. 6 data endpoints. Authenticated with an x-oanor-key; fair-use rate limits per plan.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/mma-api/..."
```

## Pricing
- **Free** (Free) — 3,100 calls/Mo, 5 req/s
- **Starter** ($8/Mo) — 52,000 calls/Mo, 15 req/s
- **Pro** ($33/Mo) — 290,000 calls/Mo, 30 req/s
- **Mega** ($97/Mo) — 1,350,000 calls/Mo, 80 req/s

## Endpoints

### Events

#### `GET /v1/event` — A single event's fight card

**Parameters:**
- `id` (query, required, string) — Event id Example: `600058949`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/mma-api/v1/event?id=600058949"
```

**Response:**
```json
{
    "data": {
        "event": {
            "id": "600058949",
            "date": "2026-06-06T21:00Z",
            "name": "UFC Fight Night: Muhammad vs. Bonfim",
            "fights": [
                {
                    "id": "401870073",
                    "result": {
                        "method": "Final",
                        "winner": "Ketlen Souza"
                    },
                    "status": "Final",
                    "fighters": [
                        {
                            "name": "Ariane Carnelossi",
                            "record": "15-5-0",
                            "winner": false
                        },
                        {
                            "name": "Ketlen Souza",
                            "record": "17-6-0",
                            "winner": true
                        }
                    ],
                    "completed": true
                },
                {
                    "id": "401864366",
                    "result": {
                        "method": "Final",
                        "winner": "Jeisla Chaves"
                    },
                    "status": "Final",
                    "fighters": [
                        {
                            "name": "Yuneisy Duben",
                            "record": "6-2-0",
                            "winner": false
                        },
                        {
                            "name": "Jeisla Chaves",
 
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/events` — UFC events & fight cards

**Parameters:**
- `dates` (query, optional, string) — Date range YYYYMMDD-YYYYMMDD

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/mma-api/v1/events"
```

**Response:**
```json
{
    "data": {
        "count": 1,
        "events": [
            {
                "id": "600058949",
                "date": "2026-06-06T21:00Z",
                "name": "UFC Fight Night: Muhammad vs. Bonfim",
                "fights": [
                    {
                        "id": "401870073",
                        "result": {
                            "method": "Final",
                            "winner": "Ketlen Souza"
                        },
                        "status": "Final",
                        "fighters": [
                            {
                                "name": "Ariane Carnelossi",
                                "record": "15-5-0",
                                "winner": false
                            },
                            {
                                "name": "Ketlen Souza",
                                "record": "17-6-0",
                                "winner": true
                            }
                        ],
                        "completed": true
                    },
                    {
                        "id": "401864366",
                        "result": {
                            "method": "Final",
                            "winner": "Jeisla Chaves"
                        },
                        "status": "Final",
                        "fighters": [
                            {
                                "name": "Yuneisy Duben",
                       
…(truncated, see openapi.json for full schema)
```

### Rankings

#### `GET /v1/rankings` — Fighter rankings by division

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/mma-api/v1/rankings"
```

**Response:**
```json
{
    "data": {
        "count": 24,
        "divisions": [
            {
                "type": "pound-for-pound",
                "ranks": [
                    {
                        "id": "3088812",
                        "rank": 1,
                        "trend": "-",
                        "fighter": "Kamaru Usman"
                    },
                    {
                        "id": "4285679",
                        "rank": 3,
                        "trend": "-",
                        "fighter": "Israel Adesanya"
                    },
                    {
                        "id": "3933168",
                        "rank": 4,
                        "trend": "-",
                        "fighter": "Francis Ngannou"
                    },
                    {
                        "id": "3949584",
                        "rank": 5,
                        "trend": "-",
                        "fighter": "Alexander Volkanovski"
                    },
                    {
                        "id": "2506250",
                        "rank": 6,
                        "trend": "-",
                        "fighter": "Jan Blachowicz"
                    },
                    {
                        "id": "2506549",
                        "rank": 7,
                        "trend": "-",
                        "fighter": "Dustin Poirier"
                    },
                    {
                        "id": "4189320",
                    
…(truncated, see openapi.json for full schema)
```

### Fighters

#### `GET /v1/fighter` — Fighter profile

**Parameters:**
- `id` (query, required, string) — Fighter id Example: `3088812`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/mma-api/v1/fighter?id=3088812"
```

**Response:**
```json
{
    "data": {
        "fighter": {
            "id": "3088812",
            "age": 39,
            "name": "Kamaru Usman",
            "reach": "76\"",
            "active": true,
            "gender": "MALE",
            "height": "6' 0\"",
            "record": [
                {
                    "label": "Wins-Losses-Draws",
                    "value": "21-4-0"
                },
                {
                    "label": "Technical Knockout-Technical Knockout Losses",
                    "value": "9-1"
                },
                {
                    "label": "Submissions-Submission Losses",
                    "value": "1-1"
                }
            ],
            "stance": "Switch",
            "weight": "171 lbs",
            "headshot": "https://a.espncdn.com/i/headshots/mma/players/full/3088812.png",
            "nickname": "Nigerian Nightmare",
            "last_name": "Usman",
            "first_name": "Kamaru",
            "association": "ONX Sports",
            "citizenship": "Nigeria",
            "weight_class": "Welterweight",
            "date_of_birth": "11/5/1987",
            "fighting_style": "Striker,Freestyle"
        }
    },
    "meta": {
        "timestamp": "2026-06-07T16:46:39.671Z",
        "request_id": "fa35a080-b05e-4f67-9519-9184fd7b4fd7"
    },
    "status": "ok",
    "message": "Fighter retrieved successfully",
    "success": true
}
```

#### `GET /v1/search` — Search fighters

**Parameters:**
- `query` (query, required, string) — Fighter name Example: `jon jones`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/mma-api/v1/search?query=jon+jones"
```

**Response:**
```json
{
    "data": {
        "count": 4,
        "query": "jon jones",
        "fighters": [
            {
                "id": "732312d4-ec2d-f307-e7cb-7a8b04f141d0",
                "name": "Jon Jones",
                "image": "https://a.espncdn.com/i/headshots/mma/players/full/2335639.png"
            },
            {
                "id": "0b96203a-7c7a-34c8-8ef1-54f6f9721aa3",
                "name": "Weder Aparecido"
            },
            {
                "id": "23282200-c473-35ce-a261-bc9cfe04c47f",
                "name": "Jon Jones",
                "image": "https://a.espncdn.com/i/headshots/college-football/players/full/4680602.png",
                "subtitle": "UTSA Roadrunners"
            },
            {
                "id": "3859776d-213b-b76c-059d-c4d226004914",
                "name": "Jon Jones",
                "subtitle": "Bethel (TN) Wildcats"
            }
        ]
    },
    "meta": {
        "timestamp": "2026-06-07T16:46:39.850Z",
        "request_id": "d6750fb2-cb57-4594-ab34-b9809135ed20"
    },
    "status": "ok",
    "message": "Fighters retrieved successfully",
    "success": true
}
```

### News

#### `GET /v1/news` — UFC news

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/mma-api/v1/news"
```

**Response:**
```json
{
    "data": {
        "count": 6,
        "articles": [
            {
                "link": "https://www.espn.com/mma/story/_/id/48978261/ufc-white-pereira-surpasses-jones-goat-win-vs-gane",
                "type": "HeadlineNews",
                "image": "https://a.espncdn.com/photo/2025/1005/r1555849_600x400_3-2.jpg",
                "headline": "UFC's White: Pereira surpasses Jones as GOAT with win vs. Gane",
                "published": "2026-06-06T14:05:36Z",
                "description": "UFC president Dana White believes two-weight UFC champion Alex Pereira will surpass Jon Jones as the greatest MMA fighter of all time if he beats Ciryl Gane at the White House."
            },
            {
                "link": "https://www.espn.com/mma/story/_/id/48976727/hearn-advises-aspinall-not-fight-current-ufc-contract",
                "type": "HeadlineNews",
                "image": "https://a.espncdn.com/photo/2025/1020/r1562751_600x400_3-2.jpg",
                "headline": "Hearn: Aspinall shouldn't fight Pereira-Gane winner under UFC deal",
                "published": "2026-06-05T19:13:35Z",
                "description": "British boxing promoter Eddie Hearn has advised UFC heavyweight champion Tom Aspinall not to defend his title vs. the winner of  the Alex Pereira-Ciryl Gane bout under the terms of his current contract."
            },
            {
                "link": "https://www.espn.com/mma/story/_/id/48949502/ranking-mma-unbeaten-fighters-ufc-pfl",
     
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/mma-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "service": "mma-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/news": "UFC news.",
            "GET /v1/event": "A single event's full fight card by id.",
            "GET /v1/events": "UFC events & fight cards (dates=YYYYMMDD-YYYYMMDD).",
            "GET /v1/search": "Search fighters by name.",
            "GET /v1/fighter": "Fighter profile by id.",
            "GET /v1/rankings": "Fighter rankings by division (champions + contenders)."
        },
        "description": "MMA / UFC data: event fight cards and results, fighter rankings by division, fighter profiles, fighter search and UFC news. Real live data, no key."
    },
    "meta": {
        "timestamp": "2026-06-07T16:46:40.059Z",
        "request_id": "6aecae90-9d17-489a-b96f-89d40e11c6a8"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/mma-api
OpenAPI spec: https://www.oanor.com/api/mma-api/openapi.json