Conversion API

Convert images to embroidery files, create customer jobs and open their editable artwork in D3VUR.

Image → preview → dispatch

Create keys at /studio/api-keys. Keep them on your server. A key acts as its owner and cannot impersonate a customer. New pilot keys allow 100 requests per day; existing keys retain their displayed limit.

POST /api/jobs with workflow: dispatch and the brief below. Open editor_url as the customer.
POST /api/jobs/{id}/convert with a multipart file: PNG, JPEG or WebP, up to 10 MB. The server creates a vector, five machine files and an actual stitch preview. It returns the saved job, passed and quality. Automatic stitch settings are used for dispatch jobs.
GET /api/jobs/{id}/preview returns the original, vector, stitch image, interactive stitch plan, quality checks and private file IDs. Preview links expire after 10 minutes; request new links when needed.
The owning customer reviews the preview and explicitly approves it. PATCH approve_submit requires the current job revision and approved: true. Failed checks block dispatch. Changing artwork requires a new conversion and approval.
Approved workshops call GET /api/dispatch for eligible jobs, then POST claim with the current revision. Only one shop can claim a job; capacity and eligibility are checked again. The customer approves the quote and production proof before work starts.

POST /api/jobs
Authorization: Bearer d3v_...
Content-Type: application/json

{"workflow":"dispatch","title":"Team caps","brief":"Front logo",
 "service":"embroidery","garment":"cap","quantity":12,
 "width_mm":90,"height_mm":50,"machine_format":"dst",
 "country":"US","city":"Austin","fulfillment":"ship","due_date":null}

POST /api/jobs/{id}/convert
Content-Type: multipart/form-data
file: <image bytes>

PATCH /api/jobs/{id}
{"action":"approve_submit","revision":2,"approved":true}

POST /api/dispatch
{"action":"claim","id":"job-uuid","revision":3}

Stale mutations return 409. Sources and machine files remain private to job participants; eligible unassigned shops receive only a dispatch summary and an expiring preview. An automated pass is not a physical sew-out certification.

No image yet

POST /api/jobs/{id}/ideas with prompt starts a local GPU generation. Poll GET with ?id=generation-uuid, then POST action: use and generation_id to convert the finished image. The owning customer can run one queued idea at a time, up to ten per day. Prompts and generated drafts are private.

Existing integrations and advanced editing

Jobs without workflow: dispatch retain the earlier editable SVG → Stitchworks → customer-selected business flow. GET/PATCH /api/jobs/{id}/artwork uses validated Stitchworks JSON and X-Artwork-Revision. The standalone POST /api/v1/convert below returns five machine files and uses the account’s conversion allowance. These endpoints remain available; the simplified customer interface uses dispatch.

Reorders, invitations and production records

Jobs accept optional specifications: blank_supply (workshop, customer or discuss), material, garment_colour, sizes, placement and placement_notes. Artwork size is fixed once a version has been saved.

POST /api/business/invites: approved workshops create a single-use customer invitation. Pass its invite token to POST /api/jobs. Attribution is verified by the server; owner, assignment and fee fields in the request are ignored.
POST /api/jobs/{id}/reorder: the owning customer copies completed, approved artwork into a new draft. Assignment, quote, proof and delivery address are not copied. Approval runs again. Dispatch reorders currently require a new checked conversion before submission.
GET /api/jobs/{id}/operations: issues and customer feedback; production reports and costs are returned only to the assigned workshop or D3VUR staff.
POST /api/jobs/{id}/operations: revision-checked report, feedback, open_issue and resolve_issue actions. Report saves also require report_revision (0 initially). Only staff can resolve issues; open issues block production, dispatch and completion.

Quotes include fee_bps, fee_cents, fee_basis and fee_policy. These are pilot estimates: 15% for a new D3VUR match, 10% for a returning customer, and 0% for the inviting workshop. They are not charges or payouts. Customer ratings and use of workshop process notes require separate, explicit consent.

Authentication

Include your API key in the Authorization header:

Authorization: Bearer your_api_key_here

Get your API key from the Studio dashboard.

Convert Image

POST/api/v1/convert

Upload an image and receive 5 machine-ready embroidery formats with Isacord thread matching.

Request

Content-Type: multipart/form-data

Field	Type	Description
file	File	PNG, JPEG, or WebP. Max 10MB.
settings	JSON string	Optional. See settings table below.

Settings

Field	Default	Description
max_colors	3	Max thread colors (1-32)
target_width_mm	90	Output width in mm (25-300). Hat=60, chest=90, back=230
fill_density_mm	0.35	Row spacing. Draft=0.50, Standard=0.35, Premium=0.25
simplify_colors	true	Quantize image colors before vectorizing
color_precision	6	Vectorizer color sensitivity (2-12)

Example (cURL)

curl -X POST https://d3vur.app/api/v1/convert \
  -H "Authorization: Bearer your_api_key" \
  -F "[email protected]" \
  -F 'settings={"max_colors":8,"target_width_mm":60,"fill_density_mm":0.35}'

Example (Python)

import requests, json

resp = requests.post(
    "https://d3vur.app/api/v1/convert",
    headers={"Authorization": "Bearer your_api_key"},
    files={"file": open("logo.png", "rb")},
    data={"settings": json.dumps({
        "max_colors": 8,
        "target_width_mm": 60,
    })},
)

data = resp.json()
print(f"Stitches: {data['stitch_count']}")
print(f"Colors: {data['color_count']}")
for tc in data['thread_colors']:
    print(f"  Isacord {tc['isacord']} — {tc['name']}")
print(f"DST: {data['dst_url']}")
print(f"PES: {data['pes_url']}")
print(f"JEF: {data['jef_url']}")
print(f"EXP: {data['exp_url']}")
print(f"VP3: {data['vp3_url']}")

Response

{
  "job_id": "43c4e7a8-368d-4654-8b2a-8e3acc94a414",
  "status": "completed",
  "stitch_count": 3536,
  "color_count": 5,
  "estimated_minutes": 5.1,
  "output_width_mm": 60.0,
  "output_height_mm": 44.3,
  "thread_colors": [
    {"hex": "#0E3858", "name": "Royal Navy", "isacord": "3644"},
    {"hex": "#CC0000", "name": "Poinsettia", "isacord": "1902"},
    {"hex": "#FFDC00", "name": "Sunshine", "isacord": "0608"}
  ],
  "dst_url": "https://...supabase.co/.../design.dst",
  "pes_url": "https://...supabase.co/.../design.pes",
  "jef_url": "https://...supabase.co/.../design.jef",
  "exp_url": "https://...supabase.co/.../design.exp",
  "vp3_url": "https://...supabase.co/.../design.vp3",
  "preview_url": "https://...supabase.co/.../preview.png",
  "duration_ms": 1498
}

Vectorize Image

POST/api/vectorize

Convert a raster image to SVG vector graphics. Free, no authentication required.

Request

Content-Type: multipart/form-data

Field	Type	Description
file	File	PNG, JPEG, or WebP. Max 10MB.
settings	JSON string	Optional. {"colorPrecision": 6, "filterSpeckle": 4, "cornerThreshold": 60, "mode": "color"}

Example (cURL)

curl -X POST https://d3vur.app/api/vectorize \
  -F "[email protected]" \
  -F 'settings={"colorPrecision":6,"mode":"color"}'

Response

{
  "job_id": "...",
  "status": "completed",
  "svg_url": "https://...supabase.co/.../output.svg",
  "svg_inline": "<svg ...>...</svg>",
  "colors_detected": 4,
  "paths_count": 23,
  "duration_ms": 850,
  "file_size_bytes": 12480
}

Batch Convert

POST/api/convert/batchStudio only

Upload up to 50 images at once. Each is converted to DST + PES embroidery files.

Request

curl -X POST https://d3vur.app/api/convert/batch \
  -H "Authorization: Bearer your_api_key" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "[email protected]"

Response

{
  "total": 3,
  "succeeded": 2,
  "failed": 1,
  "results": [
    {"filename": "logo1.png", "status": "completed", "dst_url": "...", "pes_url": "..."},
    {"filename": "logo2.png", "status": "completed", "dst_url": "...", "pes_url": "..."},
    {"filename": "logo3.png", "status": "failed", "error": "No embroiderable regions detected"}
  ]
}

Rate Limits

Plan	Requests/Day	Price
Free	10	$0
Pro	100	$29/mo
Studio	Unlimited	$99/mo

Error Codes

Status	Meaning
400	Invalid file type or missing file
401	Missing or invalid API key
422	Conversion failed (image too complex or unsupported)
429	Rate limit exceeded

Conversion API

Convert images to embroidery files, create customer jobs and open their editable artwork in D3VUR.

Image → preview → dispatch

POST /api/jobs with workflow: dispatch and the brief below. Open editor_url as the customer.
POST /api/jobs/{id}/convert with a multipart file: PNG, JPEG or WebP, up to 10 MB. The server creates a vector, five machine files and an actual stitch preview. It returns the saved job, passed and quality. Automatic stitch settings are used for dispatch jobs.
GET /api/jobs/{id}/preview returns the original, vector, stitch image, interactive stitch plan, quality checks and private file IDs. Preview links expire after 10 minutes; request new links when needed.
The owning customer reviews the preview and explicitly approves it. PATCH approve_submit requires the current job revision and approved: true. Failed checks block dispatch. Changing artwork requires a new conversion and approval.
Approved workshops call GET /api/dispatch for eligible jobs, then POST claim with the current revision. Only one shop can claim a job; capacity and eligibility are checked again. The customer approves the quote and production proof before work starts.

POST /api/jobs
Authorization: Bearer d3v_...
Content-Type: application/json

{"workflow":"dispatch","title":"Team caps","brief":"Front logo",
 "service":"embroidery","garment":"cap","quantity":12,
 "width_mm":90,"height_mm":50,"machine_format":"dst",
 "country":"US","city":"Austin","fulfillment":"ship","due_date":null}

POST /api/jobs/{id}/convert
Content-Type: multipart/form-data
file: <image bytes>

PATCH /api/jobs/{id}
{"action":"approve_submit","revision":2,"approved":true}

POST /api/dispatch
{"action":"claim","id":"job-uuid","revision":3}

No image yet

Existing integrations and advanced editing

Reorders, invitations and production records

Jobs accept optional specifications: blank_supply (workshop, customer or discuss), material, garment_colour, sizes, placement and placement_notes. Artwork size is fixed once a version has been saved.

POST /api/business/invites: approved workshops create a single-use customer invitation. Pass its invite token to POST /api/jobs. Attribution is verified by the server; owner, assignment and fee fields in the request are ignored.
POST /api/jobs/{id}/reorder: the owning customer copies completed, approved artwork into a new draft. Assignment, quote, proof and delivery address are not copied. Approval runs again. Dispatch reorders currently require a new checked conversion before submission.
GET /api/jobs/{id}/operations: issues and customer feedback; production reports and costs are returned only to the assigned workshop or D3VUR staff.
POST /api/jobs/{id}/operations: revision-checked report, feedback, open_issue and resolve_issue actions. Report saves also require report_revision (0 initially). Only staff can resolve issues; open issues block production, dispatch and completion.

Authentication

Include your API key in the Authorization header:

Authorization: Bearer your_api_key_here

Get your API key from the Studio dashboard.

Convert Image

POST/api/v1/convert

Upload an image and receive 5 machine-ready embroidery formats with Isacord thread matching.

Request

Content-Type: multipart/form-data

Field	Type	Description
file	File	PNG, JPEG, or WebP. Max 10MB.
settings	JSON string	Optional. See settings table below.

Settings

Field	Default	Description
max_colors	3	Max thread colors (1-32)
target_width_mm	90	Output width in mm (25-300). Hat=60, chest=90, back=230
fill_density_mm	0.35	Row spacing. Draft=0.50, Standard=0.35, Premium=0.25
simplify_colors	true	Quantize image colors before vectorizing
color_precision	6	Vectorizer color sensitivity (2-12)

Example (cURL)

curl -X POST https://d3vur.app/api/v1/convert \
  -H "Authorization: Bearer your_api_key" \
  -F "[email protected]" \
  -F 'settings={"max_colors":8,"target_width_mm":60,"fill_density_mm":0.35}'

Example (Python)

import requests, json

resp = requests.post(
    "https://d3vur.app/api/v1/convert",
    headers={"Authorization": "Bearer your_api_key"},
    files={"file": open("logo.png", "rb")},
    data={"settings": json.dumps({
        "max_colors": 8,
        "target_width_mm": 60,
    })},
)

data = resp.json()
print(f"Stitches: {data['stitch_count']}")
print(f"Colors: {data['color_count']}")
for tc in data['thread_colors']:
    print(f"  Isacord {tc['isacord']} — {tc['name']}")
print(f"DST: {data['dst_url']}")
print(f"PES: {data['pes_url']}")
print(f"JEF: {data['jef_url']}")
print(f"EXP: {data['exp_url']}")
print(f"VP3: {data['vp3_url']}")

Response

{
  "job_id": "43c4e7a8-368d-4654-8b2a-8e3acc94a414",
  "status": "completed",
  "stitch_count": 3536,
  "color_count": 5,
  "estimated_minutes": 5.1,
  "output_width_mm": 60.0,
  "output_height_mm": 44.3,
  "thread_colors": [
    {"hex": "#0E3858", "name": "Royal Navy", "isacord": "3644"},
    {"hex": "#CC0000", "name": "Poinsettia", "isacord": "1902"},
    {"hex": "#FFDC00", "name": "Sunshine", "isacord": "0608"}
  ],
  "dst_url": "https://...supabase.co/.../design.dst",
  "pes_url": "https://...supabase.co/.../design.pes",
  "jef_url": "https://...supabase.co/.../design.jef",
  "exp_url": "https://...supabase.co/.../design.exp",
  "vp3_url": "https://...supabase.co/.../design.vp3",
  "preview_url": "https://...supabase.co/.../preview.png",
  "duration_ms": 1498
}

Vectorize Image

POST/api/vectorize

Convert a raster image to SVG vector graphics. Free, no authentication required.

Request

Content-Type: multipart/form-data

Field	Type	Description
file	File	PNG, JPEG, or WebP. Max 10MB.
settings	JSON string	Optional. {"colorPrecision": 6, "filterSpeckle": 4, "cornerThreshold": 60, "mode": "color"}

Example (cURL)

curl -X POST https://d3vur.app/api/vectorize \
  -F "[email protected]" \
  -F 'settings={"colorPrecision":6,"mode":"color"}'

Response

{
  "job_id": "...",
  "status": "completed",
  "svg_url": "https://...supabase.co/.../output.svg",
  "svg_inline": "<svg ...>...</svg>",
  "colors_detected": 4,
  "paths_count": 23,
  "duration_ms": 850,
  "file_size_bytes": 12480
}

Batch Convert

POST/api/convert/batchStudio only

Upload up to 50 images at once. Each is converted to DST + PES embroidery files.

Request

curl -X POST https://d3vur.app/api/convert/batch \
  -H "Authorization: Bearer your_api_key" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "[email protected]"

Response

{
  "total": 3,
  "succeeded": 2,
  "failed": 1,
  "results": [
    {"filename": "logo1.png", "status": "completed", "dst_url": "...", "pes_url": "..."},
    {"filename": "logo2.png", "status": "completed", "dst_url": "...", "pes_url": "..."},
    {"filename": "logo3.png", "status": "failed", "error": "No embroiderable regions detected"}
  ]
}

Rate Limits

Plan	Requests/Day	Price
Free	10	$0
Pro	100	$29/mo
Studio	Unlimited	$99/mo

Error Codes

Status	Meaning
400	Invalid file type or missing file
401	Missing or invalid API key
422	Conversion failed (image too complex or unsupported)
429	Rate limit exceeded