# Cornhole Scoring API
> Cornhole (bag-toss) scoring as an API, computed locally and deterministically and exactly — the points behind a game of bags, from cancellation scoring to the win and the stats. The round endpoint scores a single round with cancellation rules: a bag on the board is 1 point, in the hole is 3, and only the higher player scores, and only the difference — so a player who lands 1 on the board and 2 in the hole (7) against an opponent's 2 on and 1 in (5) nets 2 points, and a tied round scores nothing. The game endpoint applies a round's points to a running total with the win rule — official ACL play is first to 21 or more at the end of an inning with no bust, while backyard 'exact 21' rules bust a player who goes over back to 15 or 11 — and reports the new score, whether the game is won, and the points still needed. The ppr endpoint gives the headline cornhole stats: points per round (PPR) = total points ÷ rounds, plus the in-the-hole percentage from bags in the hole over bags thrown — 84 points across 20 rounds is a 4.2 PPR, and 30 of 80 bags in the hole is 37.5 %. Everything is computed locally and deterministically, so it is instant and exact. Ideal for cornhole and lawn-game apps, league and tournament scorekeepers, bracket and stats tools, and backyard game-night sites. Pure local computation — no key, no third-party service, instant. Exact integer maths. Live, nothing stored. 3 compute endpoints. Standard ACL rules; house rules vary.

## 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/cornhole-api/..."
```

## Pricing
- **Free** (Free) — 6,000 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 88,000 calls/Mo, 8 req/s
- **Pro** ($12/Mo) — 350,000 calls/Mo, 20 req/s
- **Mega** ($36/Mo) — 1,550,000 calls/Mo, 48 req/s

## Endpoints

### Cornhole

#### `GET /v1/game` — Apply a round to the running score

**Parameters:**
- `current_score` (query, required, string) — Current score Example: `18`
- `points_scored` (query, required, string) — Points scored this round Example: `4`
- `target` (query, optional, string) — Target to win (default 21) Example: `21`
- `exact` (query, optional, string) — Must hit the target exactly (bust over) Example: `false`
- `bust_to` (query, optional, string) — Score a bust resets to (default 15) Example: `15`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cornhole-api/v1/game?current_score=18&points_scored=4&target=21&exact=false&bust_to=15"
```

**Response:**
```json
{
    "data": {
        "won": true,
        "note": "Official ACL play is first to 21 or more at the end of an inning — no bust. Backyard 'exact 21' rules bust a player who goes over back to a set score (commonly 15 or 11); set exact and bust_to for that. Points to win counts down what is still needed.",
        "busted": false,
        "inputs": {
            "exact": false,
            "target": 21,
            "current_score": 18,
            "points_scored": 4
        },
        "new_score": 22,
        "points_to_win": 0
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:44.528Z",
        "request_id": "f9e97c17-245e-46a7-b0a5-e5fef212b00b"
    },
    "status": "ok",
    "message": "Game state",
    "success": true
}
```

#### `GET /v1/ppr` — Points-per-round and in-hole stats

**Parameters:**
- `points` (query, required, string) — Total points scored Example: `84`
- `rounds` (query, required, string) — Rounds thrown Example: `20`
- `bags_in_hole` (query, optional, string) — Bags in the hole Example: `30`
- `bags_thrown` (query, optional, string) — Total bags thrown Example: `80`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cornhole-api/v1/ppr?points=84&rounds=20&bags_in_hole=30&bags_thrown=80"
```

**Response:**
```json
{
    "data": {
        "ppr": 4.2,
        "note": "Points per round (PPR) = total points scored ÷ rounds thrown — the headline ACL stat; competitive players run well above 4 PPR. The in-the-hole percentage = bags in the hole ÷ bags thrown shows your touch. Pass bags_in_hole and bags_thrown to include it.",
        "inputs": {
            "points": 84,
            "rounds": 20
        },
        "in_hole_pct": 37.5
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:44.624Z",
        "request_id": "81655bfb-1eac-4199-b34e-0bac3c40bae3"
    },
    "status": "ok",
    "message": "PPR stats",
    "success": true
}
```

#### `GET /v1/round` — Cancellation scoring for a round

**Parameters:**
- `p1_on_board` (query, required, string) — Player 1 bags on the board Example: `2`
- `p1_in_hole` (query, required, string) — Player 1 bags in the hole Example: `1`
- `p2_on_board` (query, required, string) — Player 2 bags on the board Example: `1`
- `p2_in_hole` (query, required, string) — Player 2 bags in the hole Example: `2`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cornhole-api/v1/round?p1_on_board=2&p1_in_hole=1&p2_on_board=1&p2_in_hole=2"
```

**Response:**
```json
{
    "data": {
        "note": "Cornhole uses cancellation scoring: a bag on the board is 1 point, in the hole is 3. Each round only the higher player scores, and only the difference — so 7 against 5 nets 2 points to the leader. A tied round scores nothing for either side.",
        "inputs": {
            "p1_in_hole": 1,
            "p2_in_hole": 2,
            "p1_on_board": 2,
            "p2_on_board": 1
        },
        "p1_raw": 5,
        "p2_raw": 7,
        "round_winner": "p2",
        "points_awarded": 2
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:44.722Z",
        "request_id": "c2046f92-f561-418a-9a0a-a46830ab4eed"
    },
    "status": "ok",
    "message": "Round score",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "On the board = 1, in the hole = 3; cancellation scoring; game to 21 (ACL: no bust; backyard exact-21 busts to 15/11). PPR = points ÷ rounds. Standard ACL rules; house rules vary.",
        "service": "cornhole-api",
        "endpoints": {
            "GET /v1/ppr": "Points-per-round and in-the-hole percentage stats.",
            "GET /v1/game": "Apply a round's points to a running score with the win/bust rule.",
            "GET /v1/meta": "This document.",
            "GET /v1/round": "Cancellation scoring for one round from each player's bags on board and in the hole."
        },
        "description": "Cornhole (bag-toss) scoring: cancellation scoring for a round, applying a round to the game with win/bust rules, and the PPR and in-the-hole stats."
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:44.788Z",
        "request_id": "461808f3-e303-456f-b511-8f48aadc99f5"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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