# Birthday Paradox API
> Birthday-paradox and collision-probability maths as an API, computed locally and deterministically. The probability endpoint computes the chance that at least two of n people share a birthday among d equally likely days, P = 1 − Π(1 − i/d), evaluated in log space for accuracy — the famous result that just 23 people give about a 50.7 % chance, 50 people about 97 % and 70 people about 99.9 %. The people-needed endpoint inverts it: the smallest group size to reach a target probability (23 for 50 %, 57 for 99 %), with the √(2·d·ln(1/(1−p))) approximation. The collision endpoint generalises the birthday bound to any space — pass a number of buckets or a hash size in bits — and returns the collision probability P ≈ 1 − e^(−n²/2d), the rule behind hash collisions and UUID-uniqueness estimates, where a 50 % chance needs roughly 1.177·√d items. Days and buckets default to 365. Everything is computed locally and deterministically, so it is instant and private. Ideal for probability-education, security, cryptography, hashing, data-engineering and statistics app developers, collision-risk and birthday-problem tools, and teaching material. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is the birthday/collision probability; for full distributions use a probability API.

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

## Pricing
- **Free** (Free) — 5,050 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 50,500 calls/Mo, 6 req/s
- **Pro** ($11/Mo) — 232,000 calls/Mo, 15 req/s
- **Mega** ($37/Mo) — 1,295,000 calls/Mo, 40 req/s

## Endpoints

### Birthday

#### `GET /v1/collision` — Generalized collision

**Parameters:**
- `items` (query, required, string) — Number of items Example: `1000000`
- `buckets` (query, optional, string) — Number of buckets
- `bits` (query, optional, string) — Or hash size in bits (2^bits) Example: `32`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/birthdayparadox-api/v1/collision?items=1000000&bits=32"
```

**Response:**
```json
{
    "data": {
        "note": "Birthday-bound collision probability P ≈ 1 − e^(−n²/(2d)). Useful for hash collisions: a 50% chance needs roughly 1.177·√d items (≈√(d) order).",
        "inputs": {
            "bits": 32,
            "items": 1000000,
            "buckets": 4294967296
        },
        "collision_probability_approx": 1,
        "collision_probability_percent": 100
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:10.762Z",
        "request_id": "661f24bf-42a5-4b53-9754-bb9852ca98c7"
    },
    "status": "ok",
    "message": "Generalized collision",
    "success": true
}
```

#### `GET /v1/people-needed` — Group size for a probability

**Parameters:**
- `probability` (query, required, string) — Target probability (0–1 or %) Example: `0.5`
- `days` (query, optional, string) — Number of days (default 365)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/birthdayparadox-api/v1/people-needed?probability=0.5"
```

**Response:**
```json
{
    "data": {
        "note": "Smallest group size whose collision probability reaches the target. For a 50% birthday match it is 23; the approximation is √(2·d·ln(1/(1−p))).",
        "inputs": {
            "days": 365,
            "probability": 0.5
        },
        "approximation": 22.4944,
        "people_needed": 23,
        "achieved_probability": 0.50729723
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:10.867Z",
        "request_id": "568cfd46-5955-46df-81f9-180d97e12bec"
    },
    "status": "ok",
    "message": "People needed",
    "success": true
}
```

#### `GET /v1/probability` — Collision probability

**Parameters:**
- `people` (query, required, string) — Number of people Example: `23`
- `days` (query, optional, string) — Number of days (default 365)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/birthdayparadox-api/v1/probability?people=23"
```

**Response:**
```json
{
    "data": {
        "note": "Probability that at least two of n share a value among d equally likely options. With 23 people and 365 days it is about 50.7% — the famous birthday paradox.",
        "inputs": {
            "days": 365,
            "people": 23
        },
        "probability": 0.5072972343,
        "probability_percent": 50.729723,
        "no_match_probability": 0.4927027657
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:10.985Z",
        "request_id": "f9705021-06e4-4558-bb05-4308a77f8014"
    },
    "status": "ok",
    "message": "Collision probability",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Days/buckets default to 365. The exact product is used for small spaces; the e^(−n²/2d) approximation for very large ones. Handy for hash-collision and UUID-uniqueness estimates.",
        "service": "birthdayparadox-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/collision": "Generalized collision probability for a hash/bucket space (by count or bits).",
            "GET /v1/probability": "Collision probability for n people over d days.",
            "GET /v1/people-needed": "Group size needed to reach a target collision probability."
        },
        "description": "Birthday paradox and generalized collision probability."
    },
    "meta": {
        "timestamp": "2026-06-05T19:50:11.087Z",
        "request_id": "6a64595c-6f73-4b24-9eee-5d1e6d42e32b"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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