# Fuse Bead API
> Fuse-bead maths as an API, computed locally and deterministically — the bead-count, pegboard and colour numbers a Perler, Hama or melty-bead crafter plans a pixel design with. The grid endpoint turns a width × height pixel pattern into the real build: total beads = width × height, pegboards = ⌈width ÷ board⌉ × ⌈height ÷ board⌉ (a 29-peg square board for midi beads), and the finished size = beads × the bead pitch — so a 58 × 58 midi design is 3,364 beads, four pegboards and about 29 × 29 cm, in millimetres, centimetres and inches, with midi at 5 mm, mini at 2.6 mm and biggie at 9–10 mm. The palette endpoint splits the beads by colour: give it the total and a list of colour percentages and it returns the count per colour (normalised by the percent sum, so it works even when they don’t add to exactly 100) and the bags to buy at about a thousand beads each, or pass raw counts to bag them directly. Everything is computed locally and deterministically, so it is instant and private. Ideal for fuse-bead, pixel-art, kids-craft and maker app developers, pattern-to-shopping-list and project-estimator tools, and craft software. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 2 compute endpoints. For cross-stitch fabric counts use a different 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/fusebead-api/..."
```

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

## Endpoints

### FuseBead

#### `GET /v1/grid` — Beads, pegboards + size

**Parameters:**
- `width_beads` (query, required, string) — Pattern width (beads) Example: `58`
- `height_beads` (query, required, string) — Pattern height (beads) Example: `58`
- `bead_type` (query, optional, string) — midi, mini, biggie or maxi (default midi) Example: `midi`
- `board_size` (query, optional, string) — Pegboard beads per side
- `pitch_mm` (query, optional, string) — Custom bead pitch (mm)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/fusebead-api/v1/grid?width_beads=58&height_beads=58&bead_type=midi"
```

**Response:**
```json
{
    "data": {
        "note": "Total beads = width × height. Pegboards = ⌈width ÷ board⌉ × ⌈height ÷ board⌉ (default 29×29 for midi). Finished size = beads × bead pitch (midi 5 mm, mini 2.6 mm). It shrinks slightly when ironed.",
        "inputs": {
            "pitch_mm": 5,
            "bead_type": "midi",
            "board_size": 29,
            "width_beads": 58,
            "height_beads": 58
        },
        "pegboards": {
            "down": 2,
            "total": 4,
            "across": 2
        },
        "total_beads": 3364,
        "finished_size": {
            "width_cm": 29,
            "width_in": 11.42,
            "width_mm": 290,
            "height_cm": 29,
            "height_in": 11.42,
            "height_mm": 290
        }
    },
    "meta": {
        "timestamp": "2026-06-06T07:13:57.288Z",
        "request_id": "9760d92e-4f08-4436-8cec-330401855543"
    },
    "status": "ok",
    "message": "Bead grid",
    "success": true
}
```

#### `GET /v1/palette` — Beads per colour + bags

**Parameters:**
- `palette` (query, required, string) — Comma list 'colour:percent' or 'colour:count' Example: `red:50,blue:30,white:20`
- `mode` (query, optional, string) — percent or count (default percent) Example: `percent`
- `total_beads` (query, optional, string) — Total beads (percent mode) Example: `3364`
- `beads_per_bag` (query, optional, string) — Beads per bag (default 1000) Example: `1000`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/fusebead-api/v1/palette?palette=red%3A50%2Cblue%3A30%2Cwhite%3A20&mode=percent&total_beads=3364&beads_per_bag=1000"
```

**Response:**
```json
{
    "data": {
        "note": "Percent mode splits a total by each colour's share (normalised by the percent sum, so it works even if they don't add to 100). Count mode just bags the counts. Bags assume ~1000 beads each — set beads_per_bag for your supplier.",
        "colors": [
            {
                "bags": 2,
                "beads": 1682,
                "color": "red",
                "percent": 50
            },
            {
                "bags": 2,
                "beads": 1009,
                "color": "blue",
                "percent": 30
            },
            {
                "bags": 1,
                "beads": 673,
                "color": "white",
                "percent": 20
            }
        ],
        "inputs": {
            "mode": "percent",
            "total_beads": 3364,
            "beads_per_bag": 1000
        },
        "total_bags": 5,
        "total_beads": 3364
    },
    "meta": {
        "timestamp": "2026-06-06T07:13:57.399Z",
        "request_id": "c816fe5f-59a5-4999-b322-ddf0387f08f8"
    },
    "status": "ok",
    "message": "Color palette",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Bead types: midi (5 mm, 29-board), mini (2.6 mm), biggie/maxi (9–10 mm). Total beads = width × height; size = beads × pitch; pegboards tile the grid. For cross-stitch fabric counts use a different API.",
        "service": "fusebead-api",
        "endpoints": {
            "GET /v1/grid": "Total beads, pegboards and finished size for a width × height grid.",
            "GET /v1/meta": "This document.",
            "GET /v1/palette": "Bead counts per colour and bags needed, by percentage or by count."
        },
        "description": "Fuse-bead (Perler/Hama) maths: bead count, pegboards and finished size for a pixel grid, and bead counts per colour."
    },
    "meta": {
        "timestamp": "2026-06-06T07:13:57.500Z",
        "request_id": "1c3073de-0a9d-42c4-9117-9988f177fe8c"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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