API reference · v1JSON + multipart

Build embroidery into your product.

A practical REST API for private image digitising and real machine-file conversion. This page is the complete quickstart, endpoint reference and error guide.

Get an API key OpenAPI 3.1

Base URL

https://embroideryfileconverter.com/api/developer/v1

Auth

Bearer key

Rate

60/min

Jobs

Async

Keys are scoped, expire, can be revoked immediately, and are shown only once. Keep them on your server—never ship one in browser or mobile client code.

Overview Quickstart Authentication Create a job Job lifecycle Endpoint reference Errors & limits

Quickstart

Your first job in three steps.

Create a key

Select only the abilities your service needs and store the secret in a server-side secret manager.

Send the source

POST multipart form data with the workflow, output format and one private source file.

Poll the job

Use the returned workflow and job ID until status is completed or failed.

Create a conversion job · Shell

curl -X POST https://embroideryfileconverter.com/api/developer/v1/jobs \
  -H "Authorization: Bearer $EFC_API_KEY" \
  -H "Accept: application/json" \
  -F "workflow=conversion" \
  -F "format=dst" \
  -F "[email protected]"

Authentication

Scoped Bearer keys.

Send the key in the Authorization header on every request. A key can access only its owner’s jobs and only the abilities selected when it was created.

formats:read

usage:read

jobs:read

jobs:write

Authorization header

Authorization: Bearer efc_live_...
Accept: application/json

Server-side only

Do not embed a developer key in a web page, distributed desktop binary or mobile app. Proxy requests through your backend.

Need delegated user access?

AI clients should use MCP with OAuth and PKCE instead of receiving a developer API key.

POST /jobs

Pick the workflow that matches the source.

workflow=conversion

Existing machine file

Upload PES, DST, JEF or another readable embroidery format and choose a different writable output.

Required: workflow, format, file
Maximum file: 50 MB

workflow=digitising

JPG, PNG, SVG or WebP artwork

Generate a stitch preview from artwork. Finished width and maximum thread colour count are required.

Additional fields: width_mm, colour_count
Valid ranges: 10–300 mm · 1–24 colours
Maximum file: 20 MB

Single files and batches

Use file for one source or files[] for up to 10 sources. Limited free processing may accept one file per request. Every batch uses one shared workflow and output format.

202 Accepted

{
  "message": "Processing started.",
  "job": {
    "id": "01JEXAMPLEJOBID000000000",
    "status": "queued",
    "workflow": "conversion"
  },
  "jobs": [
    {
      "id": "01JEXAMPLEJOBID000000000",
      "status": "queued",
      "workflow": "conversion"
    }
  ],
  "freeUsage": {
    "previewRemaining": 2,
    "creditBalance": 0
  }
}

Creation is asynchronous

HTTP 202 means the private job was accepted, not that the machine file is ready. Persist both job.id and job.workflow; the workflow selects the status route.

queuedWaiting for a worker

processingEngine is running

completedInspect outputs and warnings

failedRead failureCode and failureReason

Polling and files

Read the result, not just the status.

A completed response includes parsed metrics, warnings, events, preview artifacts and output files. Signed URLs are short-lived; request the job again when a URL expires.

Get a processing job · Shell

curl https://embroideryfileconverter.com/api/developer/v1/jobs/conversion/01JEXAMPLEJOBID000000000 \
  -H "Authorization: Bearer $EFC_API_KEY" \
  -H "Accept: application/json"

Metrics

Stitch count, dimensions and engine-specific measurements.

Warnings

Compatibility or production notes that your UI should show.

Private files

Signed URLs last 10 minutes and still enforce ownership and unlock state.

Unlock can consume an entitlement

First inspect job.unlock or GET /usage. Calling the unlock endpoint may consume a subscription allowance or existing processing credits. Internal accounts may unlock without charge. It does not open a checkout or purchase credits.

Endpoint reference

The complete v1 surface.

OpenAPI JSON

GET/formats

Readable sources, writable outputs and compatibility warnings.

formats:read

GET/usage

Preview allowance, credits, workflow costs and reset dates.

usage:read

GET/jobs

The account’s 50 most recent private processing jobs.

jobs:read

POST/jobs

Create a conversion or image-digitising preview job.

jobs:write

GET/jobs/conversion/{id}

Inspect one owned conversion job and its outputs.

jobs:read

GET/jobs/digitising/{id}

Inspect one owned digitising job and its outputs.

jobs:read

POST/jobs/{workflow}/{id}/retry

Requeue a failed job while its private source still exists.

jobs:write

POST/jobs/{workflow}/{id}/unlock

Unlock a completed job using allowance or existing credits.

jobs:write

List responses

GET /formats returns data[] and artworkInputs[]. GET /jobs returns data[] plus freeUsage and is capped at the 50 most recent jobs.

Retry responses

Retry accepts only a failed job whose source has not expired. A successful retry returns HTTP 202 with the job reset to queued.

Errors and rate limits

Fail clearly. Retry deliberately.

401

Missing, invalid, expired or revoked key

403

Missing ability or resource belongs to another user

404

Job or private file was not found

409

Job state does not permit this action

410

Source upload has expired

422

Invalid fields, file, format or insufficient quota

429

Rate limit exceeded

422 validation error

{
  "message": "The format field is invalid.",
  "errors": {
    "format": [
      "Choose an output format different from every detected source format."
    ]
  }
}

60 requests per minute

The general limit applies per API key, with a separate network ceiling. Upload, processing and unlock routes have tighter abuse controls.

Handle HTTP 429

Respect Retry-After and use exponential backoff with jitter. Do not continuously poll completed or failed jobs.

Building for an AI agent?

Use OAuth + MCP, not an API key.

The agent guide includes connection setup, discovery URLs, OAuth PKCE, every tool schema and copy-ready JSON-RPC examples.

Open MCP docs

Need help? Contact developer support

Download the OpenAPI description