{"openapi":"3.1.0","info":{"title":"Embroidery File Converter Developer API","version":"1.0.0","description":"Create and inspect private embroidery conversion and automated digitising jobs. API keys are server-side credentials and unlock operations may consume an existing allowance or credit balance."},"servers":[{"url":"https:\/\/embroideryfileconverter.com\/api\/developer\/v1"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Capabilities"},{"name":"Account"},{"name":"Jobs"},{"name":"Private files"}],"paths":{"\/formats":{"get":{"tags":["Capabilities"],"summary":"List supported input and output formats","operationId":"listFormats","x-required-ability":"formats:read","responses":{"200":{"description":"Supported embroidery formats and artwork input extensions.","content":{"application\/json":{"schema":{"type":"object","required":["data","artworkInputs"],"properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Format"}},"artworkInputs":{"type":"array","items":{"type":"string"}}}}}}},"201":{"$ref":"#\/components\/responses\/Unauthorized"},"202":{"$ref":"#\/components\/responses\/Forbidden"},"203":{"$ref":"#\/components\/responses\/RateLimited"}}}},"\/usage":{"get":{"tags":["Account"],"summary":"Get the authenticated account allowance and credit balance","operationId":"getUsage","x-required-ability":"usage:read","responses":{"200":{"description":"Current processing allowance, costs, credits, and reset dates.","content":{"application\/json":{"schema":{"type":"object","required":["freeUsage"],"properties":{"freeUsage":{"$ref":"#\/components\/schemas\/FreeUsage"}}}}}},"201":{"$ref":"#\/components\/responses\/Unauthorized"},"202":{"$ref":"#\/components\/responses\/Forbidden"},"203":{"$ref":"#\/components\/responses\/RateLimited"}}}},"\/jobs":{"get":{"tags":["Jobs"],"summary":"List recent processing jobs","operationId":"listJobs","description":"Returns up to the 50 most recent conversion and digitising jobs owned by the key owner.","x-required-ability":"jobs:read","responses":{"200":{"description":"Recent private jobs and current account usage.","content":{"application\/json":{"schema":{"type":"object","required":["data","freeUsage"],"properties":{"data":{"type":"array","maxItems":50,"items":{"$ref":"#\/components\/schemas\/JobListItem"}},"freeUsage":{"$ref":"#\/components\/schemas\/FreeUsage"}}}}}},"201":{"$ref":"#\/components\/responses\/Unauthorized"},"202":{"$ref":"#\/components\/responses\/Forbidden"},"203":{"$ref":"#\/components\/responses\/RateLimited"}}},"post":{"tags":["Jobs"],"summary":"Create a conversion or digitising job","operationId":"createJob","description":"Use conversion for an existing embroidery file. Use digitising for JPG, JPEG, PNG, SVG, or WebP artwork. The request creates a private asynchronous preview job.","x-required-ability":"jobs:write","requestBody":{"required":true,"content":{"multipart\/form-data":{"schema":{"type":"object","required":["workflow","format"],"oneOf":[{"required":["file"]},{"required":["files"]}],"properties":{"workflow":{"type":"string","enum":["conversion","digitising"]},"file":{"type":"string","format":"binary"},"files":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","format":"binary"}},"format":{"type":"string"},"width_mm":{"type":"number","minimum":10,"maximum":300},"colour_count":{"type":"integer","minimum":1,"maximum":24},"thread_palette_key":{"type":"string","enum":["generic","isacord","madeira","brother"]},"maximum_stitch_count":{"type":"integer","minimum":1,"maximum":250000}}}}}},"responses":{"202":{"description":"One or more private jobs were accepted for asynchronous processing.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/JobAccepted"}}}},"203":{"$ref":"#\/components\/responses\/Unauthorized"},"204":{"$ref":"#\/components\/responses\/Forbidden"},"205":{"$ref":"#\/components\/responses\/ValidationError"},"206":{"$ref":"#\/components\/responses\/RateLimited"}}}},"\/jobs\/conversion\/{conversion}":{"get":{"tags":["Jobs"],"summary":"Get a conversion job","operationId":"getConversionJob","x-required-ability":"jobs:read","parameters":[{"name":"conversion","in":"path","required":true,"description":"The 26-character job identifier.","schema":{"$ref":"#\/components\/schemas\/JobId"}}],"responses":{"200":{"description":"The private processing job, files, metrics, warnings, and events.","content":{"application\/json":{"schema":{"type":"object","required":["job"],"properties":{"job":{"$ref":"#\/components\/schemas\/Job"}}}}}},"201":{"$ref":"#\/components\/responses\/Unauthorized"},"202":{"$ref":"#\/components\/responses\/Forbidden"},"203":{"$ref":"#\/components\/responses\/NotFound"},"204":{"$ref":"#\/components\/responses\/RateLimited"}}}},"\/jobs\/digitising\/{digitisingOrder}":{"get":{"tags":["Jobs"],"summary":"Get a digitising job","operationId":"getDigitisingJob","x-required-ability":"jobs:read","parameters":[{"name":"digitisingOrder","in":"path","required":true,"description":"The 26-character job identifier.","schema":{"$ref":"#\/components\/schemas\/JobId"}}],"responses":{"200":{"description":"The private processing job, files, metrics, warnings, and events.","content":{"application\/json":{"schema":{"type":"object","required":["job"],"properties":{"job":{"$ref":"#\/components\/schemas\/Job"}}}}}},"201":{"$ref":"#\/components\/responses\/Unauthorized"},"202":{"$ref":"#\/components\/responses\/Forbidden"},"203":{"$ref":"#\/components\/responses\/NotFound"},"204":{"$ref":"#\/components\/responses\/RateLimited"}}}},"\/jobs\/conversion\/{conversion}\/retry":{"post":{"tags":["Jobs"],"summary":"Retry a failed conversion job","operationId":"retryConversionJob","description":"Only failed jobs with an unexpired source can be retried.","x-required-ability":"jobs:write","parameters":[{"name":"conversion","in":"path","required":true,"description":"The 26-character job identifier.","schema":{"$ref":"#\/components\/schemas\/JobId"}}],"responses":{"202":{"description":"The failed job was reset to queued.","content":{"application\/json":{"schema":{"type":"object","required":["message","job"],"properties":{"message":{"type":"string"},"job":{"$ref":"#\/components\/schemas\/JobSummary"}}}}}},"203":{"$ref":"#\/components\/responses\/Unauthorized"},"204":{"$ref":"#\/components\/responses\/Forbidden"},"205":{"$ref":"#\/components\/responses\/NotFound"},"206":{"$ref":"#\/components\/responses\/RateLimited"},"409":{"$ref":"#\/components\/responses\/Conflict"},"410":{"$ref":"#\/components\/responses\/Gone"}}}},"\/jobs\/digitising\/{digitisingOrder}\/retry":{"post":{"tags":["Jobs"],"summary":"Retry a failed digitising job","operationId":"retryDigitisingJob","description":"Only failed jobs with an unexpired source can be retried.","x-required-ability":"jobs:write","parameters":[{"name":"digitisingOrder","in":"path","required":true,"description":"The 26-character job identifier.","schema":{"$ref":"#\/components\/schemas\/JobId"}}],"responses":{"202":{"description":"The failed job was reset to queued.","content":{"application\/json":{"schema":{"type":"object","required":["message","job"],"properties":{"message":{"type":"string"},"job":{"$ref":"#\/components\/schemas\/JobSummary"}}}}}},"203":{"$ref":"#\/components\/responses\/Unauthorized"},"204":{"$ref":"#\/components\/responses\/Forbidden"},"205":{"$ref":"#\/components\/responses\/NotFound"},"206":{"$ref":"#\/components\/responses\/RateLimited"},"409":{"$ref":"#\/components\/responses\/Conflict"},"410":{"$ref":"#\/components\/responses\/Gone"}}}},"\/jobs\/conversion\/{conversion}\/unlock":{"post":{"tags":["Jobs"],"summary":"Unlock a completed conversion job","operationId":"unlockConversionJob","description":"This action may consume an available subscription entitlement or existing processing credits. Internal accounts can unlock without charge. It never opens checkout or purchases credits.","x-required-ability":"jobs:write","parameters":[{"name":"conversion","in":"path","required":true,"description":"The 26-character job identifier.","schema":{"$ref":"#\/components\/schemas\/JobId"}}],"responses":{"200":{"description":"The machine file is unlocked and fresh signed file URLs are included.","content":{"application\/json":{"schema":{"type":"object","required":["message","job"],"properties":{"message":{"type":"string"},"job":{"$ref":"#\/components\/schemas\/Job"}}}}}},"201":{"$ref":"#\/components\/responses\/Unauthorized"},"202":{"$ref":"#\/components\/responses\/Forbidden"},"203":{"$ref":"#\/components\/responses\/NotFound"},"204":{"$ref":"#\/components\/responses\/ValidationError"},"205":{"$ref":"#\/components\/responses\/RateLimited"},"409":{"$ref":"#\/components\/responses\/Conflict"}}}},"\/jobs\/digitising\/{digitisingOrder}\/unlock":{"post":{"tags":["Jobs"],"summary":"Unlock a completed digitising job","operationId":"unlockDigitisingJob","description":"This action may consume an available subscription entitlement or existing processing credits. Internal accounts can unlock without charge. It never opens checkout or purchases credits.","x-required-ability":"jobs:write","parameters":[{"name":"digitisingOrder","in":"path","required":true,"description":"The 26-character job identifier.","schema":{"$ref":"#\/components\/schemas\/JobId"}}],"responses":{"200":{"description":"The machine file is unlocked and fresh signed file URLs are included.","content":{"application\/json":{"schema":{"type":"object","required":["message","job"],"properties":{"message":{"type":"string"},"job":{"$ref":"#\/components\/schemas\/Job"}}}}}},"201":{"$ref":"#\/components\/responses\/Unauthorized"},"202":{"$ref":"#\/components\/responses\/Forbidden"},"203":{"$ref":"#\/components\/responses\/NotFound"},"204":{"$ref":"#\/components\/responses\/ValidationError"},"205":{"$ref":"#\/components\/responses\/RateLimited"},"409":{"$ref":"#\/components\/responses\/Conflict"}}}},"\/uploads\/{upload}\/download":{"get":{"tags":["Private files"],"summary":"Download a private source, artifact, or unlocked machine file","operationId":"downloadPrivateFile","description":"Use the complete signed URL returned by a job response. Do not construct this URL manually.","x-required-ability":"jobs:read","parameters":[{"name":"upload","in":"path","required":true,"schema":{"type":"string"}},{"name":"expires","in":"query","required":true,"schema":{"type":"integer"}},{"name":"signature","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Private file stream.","content":{"application\/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"201":{"$ref":"#\/components\/responses\/Unauthorized"},"202":{"$ref":"#\/components\/responses\/Forbidden"},"203":{"$ref":"#\/components\/responses\/NotFound"},"204":{"$ref":"#\/components\/responses\/RateLimited"},"410":{"$ref":"#\/components\/responses\/Gone"}}}},"\/uploads\/{upload}\/preview":{"get":{"tags":["Private files"],"summary":"Render a private image preview","operationId":"previewPrivateFile","description":"Use the complete signed URL returned by a job response. Locked stitch previews include a server-rendered watermark, while unlocked jobs return the original preview.","x-required-ability":"jobs:read","parameters":[{"name":"upload","in":"path","required":true,"schema":{"type":"string"}},{"name":"expires","in":"query","required":true,"schema":{"type":"integer"}},{"name":"signature","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"JPEG, PNG, or WebP image stream.","content":{"image\/*":{"schema":{"type":"string","format":"binary"}}}},"201":{"$ref":"#\/components\/responses\/Unauthorized"},"202":{"$ref":"#\/components\/responses\/Forbidden"},"203":{"$ref":"#\/components\/responses\/NotFound"},"204":{"$ref":"#\/components\/responses\/RateLimited"},"410":{"$ref":"#\/components\/responses\/Gone"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"EFC API key"}},"schemas":{"Error":{"type":"object","required":["message"],"properties":{"message":{"type":"string"}}},"ValidationError":{"type":"object","required":["message","errors"],"properties":{"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}},"Format":{"type":"object","required":["format","label","readable","writable","warning"],"properties":{"format":{"type":"string","example":"pes"},"label":{"type":"string","example":"Brother PES"},"readable":{"type":"boolean"},"writable":{"type":"boolean"},"warning":{"type":["string","null"]}}},"JobSummary":{"type":"object","required":["id","status","workflow"],"properties":{"id":{"$ref":"#\/components\/schemas\/JobId"},"status":{"$ref":"#\/components\/schemas\/JobStatus"},"workflow":{"$ref":"#\/components\/schemas\/Workflow"}}},"JobAccepted":{"type":"object","required":["message","job","jobs","freeUsage"],"properties":{"message":{"type":"string"},"job":{"$ref":"#\/components\/schemas\/JobSummary"},"jobs":{"type":"array","items":{"$ref":"#\/components\/schemas\/JobSummary"}},"freeUsage":{"$ref":"#\/components\/schemas\/FreeUsage"}}},"JobId":{"type":"string","minLength":26,"maxLength":26,"description":"ULID processing job identifier."},"JobStatus":{"type":"string","enum":["queued","processing","completed","failed"]},"Workflow":{"type":"string","enum":["conversion","digitising"]},"PrivateFile":{"type":"object","required":["id","name","downloadUrl","previewUrl"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"extension":{"type":"string"},"mimeType":{"type":"string"},"size":{"type":"integer"},"checksum":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"downloadUrl":{"type":["string","null"],"format":"uri"},"previewUrl":{"type":["string","null"],"format":"uri"}}},"Job":{"type":"object","required":["id","status","formats","warnings","downloadsUnlocked"],"properties":{"id":{"$ref":"#\/components\/schemas\/JobId"},"status":{"$ref":"#\/components\/schemas\/JobStatus"},"provider":{"type":["string","null"]},"formats":{"type":"array","items":{"type":"string"}},"widthMm":{"type":"number"},"colourCount":{"type":"integer"},"attemptCount":{"type":"integer"},"metrics":{"type":["object","null"],"additionalProperties":true},"warnings":{"type":"array","items":{"type":"string"}},"failureCode":{"type":["string","null"]},"failureReason":{"type":["string","null"]},"downloadsUnlocked":{"type":"boolean"},"unlock":{"type":["object","null"],"additionalProperties":true},"source":{"$ref":"#\/components\/schemas\/PrivateFile"},"outputs":{"type":"array","items":{"type":"object","additionalProperties":true}},"artifacts":{"type":"array","items":{"type":"object","additionalProperties":true}},"events":{"type":"array","items":{"type":"object","additionalProperties":true}},"createdAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}},"JobListItem":{"type":"object","required":["id","kind","status","formats","downloadsUnlocked"],"properties":{"id":{"$ref":"#\/components\/schemas\/JobId"},"kind":{"$ref":"#\/components\/schemas\/Workflow"},"title":{"type":"string"},"status":{"$ref":"#\/components\/schemas\/JobStatus"},"formats":{"type":"array","items":{"type":"string"}},"source":{"$ref":"#\/components\/schemas\/PrivateFile"},"preview":{"oneOf":[{"$ref":"#\/components\/schemas\/PrivateFile"},{"type":"null"}]},"output":{"oneOf":[{"$ref":"#\/components\/schemas\/PrivateFile"},{"type":"null"}]},"metrics":{"type":["object","null"],"additionalProperties":true},"failureReason":{"type":["string","null"]},"downloadsUnlocked":{"type":"boolean"}}},"FreeUsage":{"type":"object","required":["limited","previewRemaining","creditBalance","digitisingCreditCost","conversionCreditCost"],"properties":{"limited":{"type":"boolean"},"dailyLimit":{"type":"integer"},"dailyUsed":{"type":"integer"},"dailyRemaining":{"type":"integer"},"monthlyLimit":{"type":"integer"},"monthlyUsed":{"type":"integer"},"monthlyRemaining":{"type":"integer"},"previewRemaining":{"type":"integer"},"creditBalance":{"type":"integer"},"digitisingCreditCost":{"type":"integer"},"conversionCreditCost":{"type":"integer"},"dailyResetsAt":{"type":["string","null"],"format":"date-time"},"monthlyResetsAt":{"type":["string","null"],"format":"date-time"},"subscriptionPlanSlug":{"type":["string","null"]},"subscriptionRenewsAt":{"type":["string","null"],"format":"date-time"}},"additionalProperties":true}},"responses":{"Unauthorized":{"description":"A valid developer API key is required.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"Forbidden":{"description":"The key lacks the required ability or the resource belongs to another account.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"NotFound":{"description":"The requested resource was not found.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"Conflict":{"description":"The current job state does not permit this action.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"Gone":{"description":"The private source upload has expired.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"ValidationError":{"description":"The request fields, source file, quota, or output format failed validation.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ValidationError"}}}},"RateLimited":{"description":"The request rate was exceeded. Respect the Retry-After response header.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until another request should be attempted."}},"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}}