# Canasta Scoring API > Canasta card-game scoring as an API, computed locally and deterministically and exactly — the point counting that makes Canasta famously fiddly, done for you. The card-value endpoint totals the point value of a hand or meld: a joker is 50, aces and twos 20, eights through kings 10, fours through sevens and black threes 5, and a red three a 100-point bonus card — so a joker, an ace, a king, a seven and a red three come to 185. The bonus endpoint adds the round bonuses: a natural (pure) canasta is 500, a mixed canasta 300, each red three 100 (all four double to 800), going out 100, and going out concealed a further 100 — two naturals, a mixed, three red threes and going out is 1,700. The hand-score endpoint nets it out: the card points you melded, plus the bonuses, minus the card points left stranded in your hand when the round ends. Everything is computed locally and deterministically, so it is instant and exact. Ideal for Canasta apps, online card-room scorekeepers, club and family game-night tools, and learning aids. Pure local computation — no key, no third-party service, instant. Exact integer maths. Live, nothing stored. 3 compute endpoints. Classic Canasta values; rule variants differ. ## 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/canasta-api/..." ``` ## Pricing - **Free** (Free) — 6,500 calls/Mo, 2 req/s - **Starter** ($4/Mo) — 90,000 calls/Mo, 8 req/s - **Pro** ($12/Mo) — 360,000 calls/Mo, 20 req/s - **Mega** ($36/Mo) — 1,600,000 calls/Mo, 48 req/s ## Endpoints ### Canasta #### `GET /v1/bonus` — Canasta and round bonuses **Parameters:** - `natural_canastas` (query, optional, string) — Number of natural canastas Example: `2` - `mixed_canastas` (query, optional, string) — Number of mixed canastas Example: `1` - `red_threes` (query, optional, string) — Red threes (0-4) Example: `3` - `going_out` (query, optional, string) — Went out this round Example: `true` - `concealed` (query, optional, string) — Went out concealed Example: `false` **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/canasta-api/v1/bonus?natural_canastas=2&mixed_canastas=1&red_threes=3&going_out=true&concealed=false" ``` **Response:** ```json { "data": { "note": "Bonuses: a natural (pure) canasta is 500, a mixed canasta 300, each red three 100 (all four double to 800), going out 100, and going out concealed a further 100. A team needs at least one canasta to go out. Red threes count against you if you have not melded.", "inputs": { "concealed": false, "going_out": true, "red_threes": 3, "mixed_canastas": 1, "natural_canastas": 2 }, "total_bonus": 1700, "going_out_points": 100, "red_three_points": 300, "mixed_canasta_points": 300, "natural_canasta_points": 1000 }, "meta": { "timestamp": "2026-06-06T15:30:41.468Z", "request_id": "802b3066-fbc2-42a2-96c4-015b0bb2f66e" }, "status": "ok", "message": "Bonuses", "success": true } ``` #### `GET /v1/card-value` — Point value of cards **Parameters:** - `cards` (query, required, string) — Comma-separated ranks (joker,a,k,7,red3,...) Example: `joker,a,k,7,red3` **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/canasta-api/v1/card-value?cards=joker%2Ca%2Ck%2C7%2Cred3" ``` **Response:** ```json { "data": { "note": "Card points in Canasta: a joker is 50; aces and twos (wild) 20; eights through kings 10; fours through sevens and black threes 5; a red three is a 100-point bonus card. These are the values that count toward melds and the minimum opening meld — bonuses for canastas and going out are separate.", "inputs": { "cards": "joker,a,k,7,red3" }, "breakdown": { "7": 5, "a": 20, "k": 10, "red3": 100, "joker": 50 }, "total_points": 185 }, "meta": { "timestamp": "2026-06-06T15:30:41.562Z", "request_id": "bafee282-5f1e-43c6-b931-cbd3b97847bf" }, "status": "ok", "message": "Card value", "success": true } ``` #### `GET /v1/hand-score` — Net hand score **Parameters:** - `melded_points` (query, required, string) — Card points melded Example: `200` - `bonus_points` (query, optional, string) — Bonus points Example: `700` - `hand_points` (query, optional, string) — Card points left in hand Example: `45` **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/canasta-api/v1/hand-score?melded_points=200&bonus_points=700&hand_points=45" ``` **Response:** ```json { "data": { "note": "Hand score = the card points you melded, plus the canasta/red-three/going-out bonuses, minus the card points left in your hand when the round ends. Cards still in hand are a straight penalty, so meld them or go out. First team to 5,000 points wins the game.", "inputs": { "hand_points": 45, "bonus_points": 700, "melded_points": 200 }, "net_score": 855 }, "meta": { "timestamp": "2026-06-06T15:30:41.649Z", "request_id": "16b34480-a09f-4859-b9ce-64aaec45f20f" }, "status": "ok", "message": "Hand score", "success": true } ``` ### Meta #### `GET /v1/meta` — Spec **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/canasta-api/v1/meta" ``` **Response:** ```json { "data": { "notes": "Classic Canasta values: joker 50, A/2 20, 8–K 10, 4–7 & black 3 = 5, red 3 = 100. Canasta 500/300, red threes 100 (×2 if all four), going out 100 (+100 concealed). Game to 5,000. Rule variants differ.", "service": "canasta-api", "endpoints": { "GET /v1/meta": "This document.", "GET /v1/bonus": "Canasta, red-three and going-out bonuses.", "GET /v1/card-value": "Total point value of a list of cards (comma-separated ranks).", "GET /v1/hand-score": "Net hand score = melded points + bonuses − points in hand." }, "description": "Canasta scoring: card point values, meld/canasta/red-three/going-out bonuses, and the net hand score." }, "meta": { "timestamp": "2026-06-06T15:30:41.754Z", "request_id": "d0327439-2fe5-42ab-a0a7-614039810ee9" }, "status": "ok", "message": "Meta", "success": true } ``` --- Marketplace page: https://www.oanor.com/api/canasta-api OpenAPI spec: https://www.oanor.com/api/canasta-api/openapi.json