# Embroidery File Converter Developer API

Canonical page: https://embroideryfileconverter.com/developers

Build embroidery workflows with a private REST API for image digitising, file conversion, job status, validated outputs and signed downloads.

## Choose the right integration

- Use the REST API on this page for a backend, SaaS product, ecommerce workflow, automation, or server-side application.
- Use the [AI agent and MCP documentation](https://embroideryfileconverter.com/ai-agents) when an assistant should act on behalf of a user through OAuth.

Do not put a developer API key in browser JavaScript, a mobile application, or a distributed desktop binary.

## Base URL and authentication

- Base URL: `https://embroideryfileconverter.com/api/developer/v1`
- Authentication: `Authorization: Bearer efc_live_...`
- Job content type: `multipart/form-data`
- General default rate limit: 60 requests per minute per key, with a separate network ceiling
- Signed file URL lifetime: 10 minutes
- [OpenAPI 3.1 description](https://embroideryfileconverter.com/developers/openapi.json)
- [Create or revoke API keys](https://embroideryfileconverter.com/developers/keys)

API keys are shown once, stored only as SHA-256 hashes, expire, and can be revoked immediately. Available abilities are `formats:read`, `usage:read`, `jobs:read`, and `jobs:write`.

## Quickstart: create a conversion job

```bash
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 "file=@design.pes"
```

The API returns HTTP 202 because processing is asynchronous:

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

Persist both `job.id` and `job.workflow`. Poll the workflow-specific job endpoint until status becomes `completed` or `failed`.

## Job creation fields

### Conversion

Use `workflow=conversion` for an existing embroidery machine file.

- Required: `workflow`, `format`, and either `file` or `files[]`
- Maximum source size: 50 MB per file
- The output `format` must be writable and different from the detected source format.

### Digitising

Use `workflow=digitising` for JPG, JPEG, PNG, SVG, or WebP artwork.

- Required: `workflow`, `format`, either `file` or `files[]`, `width_mm`, and `colour_count`
- `width_mm`: number from 10 through 300
- `colour_count`: integer from 1 through 24
- Maximum source size: 20 MB per file

`files[]` accepts up to 10 sources in one batch. Accounts under limited free processing may be restricted to one source per request. Every file in a batch uses the same workflow and output format.

## Poll a job

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

Possible statuses are `queued`, `processing`, `completed`, and `failed`. A detailed job response contains metrics, warnings, failure information, events, preview artifacts, outputs, unlock state, and temporary signed file URLs. Request the job again when a signed URL expires.

## Complete endpoint reference

- `GET /formats` requires `formats:read` and returns `data[]` plus `artworkInputs[]`.
- `GET /usage` requires `usage:read` and returns `freeUsage`, including allowance, credits, workflow costs, and reset dates.
- `GET /jobs` requires `jobs:read` and returns `data[]` plus `freeUsage` for up to 50 recent owned jobs.
- `POST /jobs` requires `jobs:write` and creates one or more private asynchronous preview jobs.
- `GET /jobs/conversion/{id}` requires `jobs:read` and returns one owned conversion job.
- `GET /jobs/digitising/{id}` requires `jobs:read` and returns one owned digitising job.
- `POST /jobs/conversion/{id}/retry` and `POST /jobs/digitising/{id}/retry` require `jobs:write`. Only failed jobs with an unexpired source may be retried.
- `POST /jobs/conversion/{id}/unlock` and `POST /jobs/digitising/{id}/unlock` require `jobs:write`. The job must be completed.
- Signed `GET /uploads/{id}/download` and `GET /uploads/{id}/preview` URLs require `jobs:read`; use the complete URL returned in the job response rather than constructing it.

## Unlock behavior

Inspect `job.unlock` or `GET /usage` before unlocking. An unlock request can consume an available subscription entitlement or processing credits already on the account. Internal accounts may unlock without charge. It does not open checkout or purchase credits. Insufficient quota or credits returns a validation error.

## Errors and retry behavior

- `401`: missing, malformed, expired, or revoked developer key
- `403`: missing key ability or resource belongs to another account
- `404`: job or private file was not found
- `409`: the current job state does not permit retry or unlock
- `410`: the private source upload expired
- `422`: invalid fields, source file, output format, or insufficient quota
- `429`: a rate limit was exceeded; honor `Retry-After` and use exponential backoff with jitter

Job creation is also protected by upload and processing limits, and unlock routes have a tighter billing-action limit. Avoid aggressive polling and stop after a terminal status.

## Security model

Customer files remain private. Every job query is restricted to the API-key owner, signed URLs expire, downloadable machine files remain locked until entitlement checks pass, and key abilities are enforced before the requested operation executes.

## Related pages

- [AI agents and MCP](https://embroideryfileconverter.com/ai-agents)
- [Supported embroidery formats](https://embroideryfileconverter.com/formats)
- [Privacy and file retention](https://embroideryfileconverter.com/privacy)