# Cross-Stitch API
> Cross-stitch and embroidery maths as an API, computed locally and deterministically — the design-size, fabric and floss numbers a cross-stitcher, embroidery designer or needlework-shop works a project out with. The design-size endpoint turns a stitch count and a fabric count (stitches per inch) into the finished size: size = stitch count ÷ fabric count, so a 140 × 98 design on 14-count Aida finishes at 10 × 7 inches (25.4 × 17.8 cm), smaller on 18-count and larger on 11-count because a higher count packs more stitches per inch — and it returns the total stitch count (width × height) that drives the floss and the hours. The fabric-needed endpoint adds a margin on every side to give the fabric to cut: design size + twice the margin per dimension, with the usual 3 inches per side for hooping, framing and finishing, so a 10 × 7 design wants a 16 × 13 inch cut. The thread-length endpoint estimates floss from the geometry of a full cross — the front two diagonals plus the back returns is about (2√2 + 2) ÷ fabric count inches per stitch — so 5,000 stitches on 14-count is roughly 1,724 inches, about 44 m, and it estimates the skeins given the number of strands (a 6-strand skein is ~8 m). Everything is computed locally and deterministically, so it is instant and private. Ideal for cross-stitch and embroidery pattern tools, needlework-shop and kit apps, and craft-project calculators. Pure local computation — no key, no third-party service, instant. Floss figures are planning estimates — buy a little extra and dye-lot match. 3 compute endpoints. For sewing yardage use a sewing API; for knitting gauge a knitting 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/embroidery-api/..."
```

## Pricing
- **Free** (Free) — 5,800 calls/Mo, 2 req/s
- **Starter** ($7/Mo) — 54,000 calls/Mo, 6 req/s
- **Pro** ($22/Mo) — 238,000 calls/Mo, 15 req/s
- **Mega** ($71/Mo) — 1,080,000 calls/Mo, 40 req/s

## Endpoints

### CrossStitch

#### `GET /v1/design-size` — Finished size from stitch and fabric count

**Parameters:**
- `stitch_count_w` (query, required, string) — Stitches across (width) Example: `140`
- `stitch_count_h` (query, required, string) — Stitches down (height) Example: `98`
- `fabric_count` (query, required, string) — Fabric count (stitches per inch, e.g. 14) Example: `14`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/embroidery-api/v1/design-size?stitch_count_w=140&stitch_count_h=98&fabric_count=14"
```

**Response:**
```json
{
    "data": {
        "note": "The finished size = the stitch count ÷ the fabric count (stitches per inch). A 140 × 98 design on 14-count Aida is 10 × 7 inches (25.4 × 17.8 cm); the same chart on 18-count finishes smaller and on 11-count larger, because a higher count packs more stitches per inch. The total stitch count (width × height) drives the floss and the hours.",
        "inputs": {
            "fabric_count": 14,
            "stitch_count_h": 98,
            "stitch_count_w": 140
        },
        "width_cm": 25.4,
        "width_in": 10,
        "height_cm": 17.78,
        "height_in": 7,
        "total_stitches": 13720
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:52.992Z",
        "request_id": "e52d770f-4acd-409d-9256-7559fa791ec1"
    },
    "status": "ok",
    "message": "Design size",
    "success": true
}
```

#### `GET /v1/fabric-needed` — Cut fabric size with margin

**Parameters:**
- `design_width_in` (query, required, string) — Design width (in) Example: `10`
- `design_height_in` (query, required, string) — Design height (in) Example: `7`
- `margin_in` (query, optional, string) — Margin per side (in, default 3) Example: `3`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/embroidery-api/v1/fabric-needed?design_width_in=10&design_height_in=7&margin_in=3"
```

**Response:**
```json
{
    "data": {
        "note": "The fabric to cut = the design size plus a margin on every side, so add twice the margin to each dimension. The usual margin is 3 inches per side for hooping, framing and finishing — a 10 × 7 design wants a 16 × 13 inch cut. Skimp on the margin and there is no room to mount or frame the finished piece.",
        "inputs": {
            "margin_in": 3,
            "design_width_in": 10,
            "design_height_in": 7
        },
        "fabric_width_cm": 40.64,
        "fabric_width_in": 16,
        "fabric_height_cm": 33.02,
        "fabric_height_in": 13
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:53.078Z",
        "request_id": "a64abdab-9564-4fb5-bcce-3c69852259b6"
    },
    "status": "ok",
    "message": "Fabric needed",
    "success": true
}
```

#### `GET /v1/thread-length` — Floss length and skeins

**Parameters:**
- `stitch_count` (query, required, string) — Total stitches Example: `5000`
- `fabric_count` (query, required, string) — Fabric count (stitches per inch) Example: `14`
- `strands` (query, optional, string) — Strands used (default 2) Example: `2`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/embroidery-api/v1/thread-length?stitch_count=5000&fabric_count=14&strands=2"
```

**Response:**
```json
{
    "data": {
        "note": "Floss use is estimated from the geometry of a full cross on the fabric: front two diagonals plus the back returns is about (2√2 + 2) ÷ fabric count inches per stitch. 5,000 stitches on 14-count is roughly 1,724 inches — about 44 m of finished stitching. A 6-strand skein is ~8 m, so stitching with 2 strands yields ~24 m of usable thread per skein; this is a planning estimate — buy a little extra and dye-lot match.",
        "inputs": {
            "strands": 2,
            "fabric_count": 14,
            "stitch_count": 5000
        },
        "total_thread_m": 43.8,
        "skeins_estimate": 1.83,
        "total_thread_in": 1724.4,
        "thread_per_stitch_in": 0.3449
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:53.163Z",
        "request_id": "61c11709-b67d-4bb2-acee-1836ce8803d2"
    },
    "status": "ok",
    "message": "Thread length",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Fabric count = stitches per inch. size = stitch_count/count; fabric = design + 2·margin; thread/stitch ≈ (2√2+2)/count inches. For sewing yardage use a sewing API; for knitting gauge a knitting API.",
        "service": "embroidery-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/design-size": "Finished width/height and total stitches from stitch count and fabric count.",
            "GET /v1/fabric-needed": "Cut fabric size from the design size and a margin.",
            "GET /v1/thread-length": "Floss length and skein estimate from stitch count and fabric count."
        },
        "description": "Cross-stitch / embroidery maths: finished design size from stitch and fabric count, cut fabric size with margins, and floss length."
    },
    "meta": {
        "timestamp": "2026-06-07T08:17:53.219Z",
        "request_id": "af5e5da3-bfac-4174-a167-bdd792be90b2"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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