# Cribbage Score API
> Cribbage hand-scoring maths as an API, computed locally and deterministically — the count a cribbage player, app or league tallies a hand by. The score endpoint takes the four-card hand and the starter (cut) card and returns the full breakdown by the rules: every distinct combination of cards summing to fifteen scores 2, each pair scores 2 (so three of a kind is 6 and four is 12), each run of three or more consecutive cards scores its length — counting the duplicate runs that pairs create — a four-card flush in the hand is 4 (five with the starter is 5, and the crib only scores a five-card flush), and his nobs, a Jack in hand matching the starter’s suit, is 1. It correctly scores the famous best hand, J-5-5-5 with a fifth 5 cut, at the maximum 29. The count endpoint tallies just fifteens, pairs and runs for any one to eight cards — useful for checking part of a hand or the pegging pile. Everything is computed locally and deterministically, so it is instant and private. Ideal for cribbage, card-game, board-game-companion and scoring app developers, score-verification and teaching tools, and game software. Pure local computation — no key, no third-party service, instant. Cards as rank+suit (5H, TD, JS). Live, nothing stored. 2 compute endpoints.

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

## Pricing
- **Free** (Free) — 7,600 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 58,600 calls/Mo, 6 req/s
- **Pro** ($11/Mo) — 237,200 calls/Mo, 15 req/s
- **Mega** ($36/Mo) — 1,368,000 calls/Mo, 40 req/s

## Endpoints

### Cribbage

#### `GET /v1/count` — Partial count

**Parameters:**
- `cards` (query, required, string) — Any 1–8 cards Example: `5H,5S,5C`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cribbage-api/v1/count?cards=5H%2C5S%2C5C"
```

**Response:**
```json
{
    "data": {
        "note": "Counts only fifteens, pairs and runs for any set of cards — handy for checking part of a hand or the running pile. Flush and his-nobs depend on the full hand and the starter, so use /v1/score for a complete count.",
        "total": 8,
        "inputs": {
            "cards": [
                "5H",
                "5S",
                "5C"
            ]
        },
        "breakdown": {
            "runs": 0,
            "pairs": 6,
            "fifteens": 2
        }
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:50.996Z",
        "request_id": "d2a29307-3d88-4f25-9371-daa11dff0262"
    },
    "status": "ok",
    "message": "Partial count",
    "success": true
}
```

#### `GET /v1/score` — Score a hand

**Parameters:**
- `hand` (query, required, string) — Four cards (rank+suit) Example: `5H,5S,5C,JD`
- `starter` (query, required, string) — Starter / cut card Example: `5D`
- `is_crib` (query, optional, string) — true for the crib (5-card flush only) Example: `false`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/cribbage-api/v1/score?hand=5H%2C5S%2C5C%2CJD&starter=5D&is_crib=false"
```

**Response:**
```json
{
    "data": {
        "note": "Cribbage hand value: every combination summing to fifteen = 2, each pair = 2, each run of 3+ = its length, a four-card flush = 4 (five = 5; the crib only scores a five-card flush), and his nobs — a Jack matching the starter's suit — = 1. The legendary best hand, J5-555 with a matching 5 cut, scores 29.",
        "total": 29,
        "inputs": {
            "hand": [
                "5H",
                "5S",
                "5C",
                "JD"
            ],
            "is_crib": false,
            "starter": "5D"
        },
        "breakdown": {
            "nobs": 1,
            "runs": 0,
            "flush": 0,
            "pairs": 12,
            "fifteens": 16
        }
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:51.088Z",
        "request_id": "dfa72289-642c-4bb0-a87a-291ce68c8f49"
    },
    "status": "ok",
    "message": "Hand score",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Cards as rank+suit: A,2-9,T/10,J,Q,K and H,D,C,S (e.g. '5H', 'TD', 'JS'). Fifteens use face value (J/Q/K = 10, A = 1); runs use rank order. The crib only scores a 5-card flush. Maximum 29.",
        "service": "cribbage-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/count": "Fifteens, pairs and runs for any 1–8 cards (no flush/nobs).",
            "GET /v1/score": "Score a 4-card hand with the starter card (set is_crib for the crib's flush rule)."
        },
        "description": "Cribbage hand scoring: fifteens, pairs, runs, flush and his-nobs for a hand plus the starter, and a partial count of any cards."
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:51.180Z",
        "request_id": "3e830259-5e62-42a1-bd25-a141fe6ceec1"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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