Developer API — engine v9

Embroidery digitizing,
one POST request.

Send a base64 image to the StitchFast API and receive a production-ready embroidery file back in seconds — the same v9 engine behind the web digitizer, metered per file with automatic refunds on failure.

Get your API key Quick start

.DST .PES .JEF .EXP .VP3 .XXX .HUS

Overview

How it works

One endpoint. You authenticate with an API key, spend one credit per generated file, and get a ZIP bundle back. If generation fails for any reason, the credit is refunded automatically — you only ever pay for files that reach you.

Create a key

Generate an API key in your developer dashboard. It is shown once — only a hash is stored on our side.

POST your image

Send a base64 PNG, JPG or HEIC with your target width and format. Options mirror the web digitizer.

Receive the ZIP

The response is a ZIP containing your embroidery file plus colour-companion files, a thread key and a PNG preview of the result.

Authentication

API keys

All requests are authenticated with a key beginning sf_live_, created and revoked from your developer dashboard. Pass it in either header form — both are equivalent:

Header — Bearer

Authorization: Bearer sf_live_YOUR_KEY

Header — X-API-Key

X-API-Key: sf_live_YOUR_KEY

Keys are shown once. We store only a SHA-256 hash of your key, so it can never be recovered from your account — if a key is lost, revoke it and create a new one. Keys are account-scoped: every key you create draws from the same API credit balance.

Requests are rate-limited to 30 per minute per key. Breaching the limit returns 429 and does not spend a credit. If you need more sustained throughput, create additional keys or contact us.

Quick start

Your first file in one request

There is a single endpoint. POST a JSON body, receive a ZIP (binary) on success or a JSON error on failure:

POSThttps://api.stitchfast.co.uk/v1/digitize

curl

curl -X POST https://api.stitchfast.co.uk/v1/digitize \
  -H "Authorization: Bearer sf_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image":"<base64 png/jpg>","widthMM":100,"format":"dst","name":"Client Logo"}' \
  -o design.zip

Python

import base64, requests

URL = "https://api.stitchfast.co.uk/v1/digitize"

with open("logo.png", "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode()

r = requests.post(URL,
    headers={"Authorization": "Bearer sf_live_YOUR_KEY"},
    json={"image": image_b64, "widthMM": 100, "format": "dst", "name": "Client Logo"},
    timeout=120)

if r.status_code == 200:
    with open("design.zip", "wb") as out:
        out.write(r.content)
    print("Credits remaining:", r.headers["X-Credits-Remaining"])
    print("Stitches:", r.headers["X-Stitch-Count"])
else:
    print(r.status_code, r.json()["error"])   # credit auto-refunded on any non-200

Node.js

import { readFile, writeFile } from "node:fs/promises";

const URL = "https://api.stitchfast.co.uk/v1/digitize";
const image = (await readFile("logo.png")).toString("base64");

const res = await fetch(URL, {
  method: "POST",
  headers: {
    "Authorization": "Bearer sf_live_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ image, widthMM: 100, format: "dst", name: "Client Logo" }),
});

if (res.ok) {
  await writeFile("design.zip", Buffer.from(await res.arrayBuffer()));
  console.log("Credits remaining:", res.headers.get("X-Credits-Remaining"));
} else {
  const { error } = await res.json();       // credit auto-refunded on any non-200
  console.error(res.status, error);
}

A data:image/png;base64,... data URI is also accepted for the image field — the prefix is stripped automatically. Transparent PNGs are composited onto a white background before digitizing.

Request

Request parameters

JSON body. Only image is required — every other field has a production-tuned default. Unknown fields are ignored.

Field	Required	Default	Description
image	required	—	Base64-encoded PNG, JPG or HEIC. Data URIs accepted. Transparency is composited onto white.
widthMM	optional	100	Finished design width in millimetres. Must be between 10 and 300.
heightMM	optional	auto	Finished height in millimetres. When omitted, height follows the source aspect ratio. When set, the design is scaled anisotropically; if the requested aspect is within 2% of the source, uniform scaling is used.
format	optional	dst	Output format: dst, pes, jef, exp, vp3, xxx or hus.
name	optional	StitchFast Design	Design name — used for the filenames inside the ZIP bundle.
maxColours	optional	6	Thread colour cap, 2 to 16. Match your artwork's real colour count for the cleanest result.
density	optional	3.0	Fill density in stitch lines per millimetre. 3.0 is the commercial standard (0.40mm spacing); higher values increase coverage, stiffness and sew time.
stitchLengthMM	optional	1.6	Target stitch length in millimetres for fills and runs.
pullCompMM	optional	0.25	Pull compensation in millimetres, offsetting fabric pull. Satin columns additionally receive width-scaled compensation automatically.
underlay	optional	light	Underlay stitching level to stabilise the fabric before top stitching.
fillAngleDeg	optional	auto	Fill stitch angle in degrees. When omitted, the engine picks per region.
minRegionMM2	optional	1.0	Advanced. Smallest region area (mm²) that will be stitched — smaller shapes are dropped.
minDimMM	optional	0.8	Advanced. Smallest region dimension (mm) that will be stitched. Regions under 1.3mm wide become a running stitch rather than satin.
satinMaxWidthMM	optional	5.0	Advanced. Widest column that will be stitched as satin; wider regions become tatami fill.
satinMinAspect	optional	1.6	Advanced. Minimum length-to-width ratio for a region to qualify as a satin column.

Limits: widthMM must be 10–300 (no mainstream single-field hoop exceeds 300mm) and total stitches are capped at 150,000 per design. Every generated file is re-parsed and validated before delivery — a corrupt file can never reach you; validation failures return a 500 and your credit is refunded.

Response

What you get back

A successful request returns 200 with a binary ZIP bundle (Content-Type: application/zip). The bundle always has the same five files, regardless of chosen format — the companions restore colour metadata that DST and EXP strip natively, and a rendered PNG lets you show the result without opening the stitch file:

File	Contents
{name}.{ext}	Your embroidery file in the requested format — ready for the machine.
{name}.edr	Embird colour palette companion file.
{name}.inf	Thread information file read by commercial machines.
{name}-threads.txt	Human-readable thread key: colour order with Madeira-matched thread references.
{name}-preview.png	Flat PNG render of the generated stitches on a white background — a true stitch-out of the file. Use it for on-screen previews or thumbnails without any embroidery software.

Useful metadata rides on the response headers (all exposed to browser clients via CORS):

Header	Meaning
X-Credits-Remaining	Your API credit balance after this call. Check it on every response.
X-Stitch-Count	Total stitch records in the file.
X-Normal-Stitches	Normal stitches (excluding jumps, trims and colour changes).
X-Jump-Count	Jump movements.
X-Trim-Count	Thread trims.
X-Color-Changes	Colour change commands.
X-Thread-Blocks	Number of thread colours used.
X-Design-WxH-Mm	Final stitched dimensions, e.g. 100.0x63.4.
X-Bundle-Contains	Comma-separated list of the files inside the ZIP.
X-Engine-Version	Digitizing engine version that produced the file.
X-Digitise-Time-Ms	Total generation time in milliseconds.

Errors

Error handling

Any failure returns a JSON body in this shape, with the HTTP status carrying the category:

Error body

{
  "error": "Human-readable message describing what went wrong",
  "version": "9.x.x"
}

Status	Example messages	What to do
400	"No image provided" · "Image base64 decode failed" · "Unsupported format" · "widthMM must be between 10 and 300"	Fix the request body and retry. The credit is refunded.
401	"Missing or malformed API key" · "Invalid API key" · "API key has been revoked"	Check the header name and key value, or create a new key in the dashboard. No credit is spent.
402	"Insufficient API credits — purchase a pack at stitchfast.co.uk/account"	Top up with a credit pack. No credit is spent.
429	"Rate limit exceeded (30/min)"	Back off and retry after the current minute window. No credit is spent.
500	"Engine error: ..." · "Generated file failed read-back validation" · "Read-back found a ...mm movement — file rejected before delivery"	Retry; if a specific image consistently fails, contact us with the image. The credit is refunded.

Automatic refunds. One credit is deducted when your request is accepted, and refunded on any non-200 response — validation errors, engine errors, everything. Your balance only ever decreases for files you actually receive. The refund is reflected in the creditsAfter value shown in your usage history.

Credits

API credit packs

One credit equals one generated embroidery file. Prepaid, no expiry, no subscription. API credits are a separate pool from your web design credits — the web Unlimited plan does not include API access. Purchase from your developer dashboard.

FAQ

Developer questions

Which image types can I send?

PNG, JPG and HEIC, base64-encoded (a data URI prefix is fine). Transparent images are composited onto a white background before digitizing, so the background is detected and stripped consistently. Clean, high-contrast artwork such as logos, text and line art digitizes best.

How long does a request take?

Typically a few seconds, depending on image complexity, size and colour count. Set a client timeout of at least 120 seconds to cover cold starts and complex designs. The X-Digitise-Time-Ms header on each response tells you the exact generation time.

Can I show my users a preview of the design?

Yes. Every ZIP includes a {name}-preview.png — a flat render of the actual generated stitches on a white background. Extract it from the bundle and display it directly; there is no separate endpoint and no extra credit. It is a true stitch-out of the file, so it reflects the real result rather than the uploaded image.

Am I charged for failed requests?

No. A credit is deducted when the request is accepted and automatically refunded on any non-200 response. Authentication failures, rate limits and insufficient-credit responses never spend a credit in the first place.

Can I use my web Unlimited plan with the API?

No — API access is always metered per file from its own credit pool, separate from web design credits. This keeps API pricing predictable for volume integrations. Packs start at 25 credits and never expire.

Where do I see my usage?

Your developer dashboard shows your last 30 API calls — timestamp, endpoint, result, generation time and credit balance after each call — alongside key management and credit purchases.

Is the output really production-ready?

Every file is re-parsed and validated before delivery: headers, stitch data and movement deltas are checked against format limits (12.1mm per movement for DST/EXP). A file that fails validation is never delivered — you get a 500 and a refund instead. The bundle includes colour companion files and a Madeira-matched thread key for the machine operator.

Start integrating today

Create a key, send your first request, and ship embroidery files from your own product in minutes.

Open the developer dashboard