API / DOCUMENTATION

STL Converter API

Use the conversion service to create asynchronous jobs, inspect mesh statistics, and download the generated file. Deploy it behind your own access controls when exposing it to a wider audience.

Base URL and access

Use the same origin that serves this page as the API base URL. Each job returns a capability token in the JSON response; send it in the X-Job-Token header for status and cancellation. Bind jobs to an authenticated account and enforce plan quotas before sharing the service publicly.

const API_BASE = 'https://your-domain.example';

Endpoints

GET /api/health checks whether the service is available.
POST /api/jobs accepts multipart fields operation, outputFormat, options, and file.
GET /api/jobs/:id returns queued, processing, completed, or failed status plus mesh analysis.
DELETE /api/jobs/:id cancels a queued job before processing starts.
GET /api/jobs/:id/download downloads the completed result.

Create a conversion job

curl -X POST http://localhost:4173/api/jobs -F operation=convert -F outputFormat=stl -F [email protected]

JavaScript clients can send the same multipart fields with FormData:

const form = new FormData();
form.append('operation', 'convert');
form.append('outputFormat', 'stl');
form.append('file', file);
const response = await fetch(`${API_BASE}/api/jobs`, { method: 'POST', body: form });
const job = await response.json();

Multipart fields

Field	Required	Values and notes
`operation`	Yes	`convert`, `analyze`, or `repair`.
`file`	Yes	One supported file, up to 250 MB.
`outputFormat`	For convert	`stl`, `obj`, `glb`, `fbx`, or `step`.
`options`	No	JSON object for image relief, SVG extrusion, or STEP tessellation settings.

Poll and download

curl -H "X-Job-Token: JOB_TOKEN" http://localhost:4173/api/jobs/JOB_ID
# Use the result.downloadUrl returned by the completed response:
curl -L -o result.stl "http://localhost:4173/api/jobs/JOB_ID/download?download_token=DOWNLOAD_TOKEN"

Poll the status URL with the X-Job-Token header until it returns completed or failed. A completed response includes a relative result.downloadUrl containing a separate download-only token that expires after 10 minutes. API clients can also download with the original capability in the X-Job-Token header.

Error codes

HTTP	Code	When it occurs
400	`MULTIPART_REQUIRED`, `FILE_REQUIRED`, `UPLOAD_LIMIT`	Request format, file field, or 250 MB upload limit is invalid.
403	`ORIGIN_NOT_ALLOWED`	The browser origin is not in the configured exact-origin allowlist.
415	`FORMAT_NOT_ALLOWED`	The uploaded extension is outside the supported input formats.
404	`JOB_NOT_FOUND`, `RESULT_MISSING`	Job expired or its generated result is unavailable.
409	`RESULT_NOT_READY`, `JOB_NOT_ACTIVE`, `JOB_ALREADY_PROCESSING`	The result is not ready, or a job cannot be cancelled after processing starts.
429	`RATE_LIMITED`, `JOB_QUEUE_FULL`, `UPLOAD_CONCURRENCY_LIMIT`	Per-client creation limit, upload concurrency, or server queue capacity was reached.
500	`INTERNAL_ERROR`	Unexpected server failure; retry after checking service logs.

Supported workflows and limits

Supported inputs include STL, OBJ, 3MF, GLB, FBX, STEP, PNG, JPG, SVG, DXF, and ZIP. Reverse exports support OBJ, GLB, FBX, and faceted STEP. Uploads are limited to 250 MB; ZIP jobs also have file-count and decompressed-size limits.

ZIP archives accept up to 100 nested files and a 128 MB decompressed/output safety budget by default. Mesh processing also enforces vertex and face limits. The default rate limit is 20 job creations per client per minute, with one active conversion and two pending jobs on the reference deployment.

Jobs and temporary files are retained only for the one-hour cleanup window. Download URLs expire after 10 minutes. Add authentication, aggregate edge rate limiting, request timeouts, a persistent result store, and container-level memory limits before exposing the API to an untrusted public network.

Back to STL Converter →