REST API
Submit files, add an optional part brief and maximum dimension, start a conversion and fetch finished 3D models over HTTP, or read a drawing's manufacturing data as JSON.
Authentication
Every request carries an API key issued in the admin area. Parts created with a key belong to the account the key was issued for.
Authorization: Bearer vlm_ab12cd34_...Submit a part
POST /api/public/v1/parts — multipart/form-data. Up to 5 files and 20 MB in total. brief, maxDimension and grouping are optional, exactly as in the app. With submit=true the part's analysis starts right away (see Start a conversion).
Single-page TIFF/TIF can be uploaded directly. It is prepared automatically for conversion while the original is retained. Export multi-page TIFF as PDF or separate PNG images. Mixed file sets containing TIFF may require a grouping review. DWG and DXF drawings are uploaded on their own, one per part.
curl -X POST https://voluminate.3dspark.de/api/public/v1/parts \
-H "Authorization: Bearer $VOLUMINATE_API_KEY" \
-F "files=@bracket-front.jpg" \
-F "files=@bracket-side.jpg" \
-F "name=Bracket" \
-F "brief=Sheet metal bracket, two M6 threads" \
-F "maxDimension=120" \
-F "maxDimensionUnit=mm" \
-F "submit=true"201 Created
{
"part": { "id": "…", "partNumber": "SET-1234", "name": "Bracket" },
"files": [ { "id": "…", "name": "bracket-front.jpg" } ],
"conversion": null,
"analysis": { "status": "pending" }
}Start a conversion
Each part is analysed before it is converted. The analysis checks that the files can be converted and sets the part's price in credits from its complexity. Starting a conversion takes two calls to POST /api/public/v1/parts/<part-id>/convert:
- The first call starts the analysis and returns
202with"conversion": null.submit=trueon upload does the same. - Poll
GET /api/public/v1/parts/<part-id>untilanalysis.statusisready. This usually takes under a minute. - Call
/convertagain. The conversion starts and its price is charged. A new account's first conversion is free.
Calling /convert while the analysis runs starts nothing new. If the analysis is rejected, the files cannot be converted: upload different files as a new part. If it failed, call /convert again to retry it.
curl -X POST https://voluminate.3dspark.de/api/public/v1/parts/<part-id>/convert \
-H "Authorization: Bearer $VOLUMINATE_API_KEY"202 Accepted (analysis running)
{ "conversion": null, "analysis": { "status": "pending" } }
200 OK (conversion started)
{ "conversion": { "id": "…", "status": "queued" } }Check status and download models
analysis.status is not_started, pending, ready, rejected or failed. conversion.status is queued, processing, completed or failed. models lists the models included in the service you paid for. Download links are signed and valid for one hour. Poll every 30–60 seconds; a run is capped at 45 minutes.
curl https://voluminate.3dspark.de/api/public/v1/parts/<part-id> \
-H "Authorization: Bearer $VOLUMINATE_API_KEY"{
"id": "…",
"partNumber": "SET-1234",
"name": "Bracket",
"brief": "Sheet metal bracket, two M6 threads",
"maxDimension": { "value": 120, "unit": "mm" },
"createdAt": "…",
"files": [ { "id": "…", "name": "bracket-front.jpg", "sizeBytes": 412000 } ],
"analysis": { "status": "ready", "message": null },
"conversion": { "id": "…", "status": "completed", "createdAt": "…", "completedAt": "…" },
"models": [
{ "id": "variant-1", "format": "stl", "sizeBytes": 812344, "downloadUrl": "https://…" }
]
}Extract drawing data (no 3D model)
Reads the manufacturing data of one technical drawing and returns it as JSON: tolerances and GD&T, surface finish, material, bounding box, weight, heat treatment, manufacturing process, quality inspection, threads and fits, revision data and cost-relevant features. No conversion runs and no credits are charged.
Send exactly one file: PDF, PNG, JPG, WEBP, TIFF, BMP, DWG or DXF. Put a drawing with several sheets into one PDF. Upload with extract=true (not together with submit=true), or start it later for a part that has one file.
curl -X POST https://voluminate.3dspark.de/api/public/v1/parts \
-H "Authorization: Bearer $VOLUMINATE_API_KEY" \
-F "files=@bracket.pdf" \
-F "name=Bracket" \
-F "extract=true"curl -X POST https://voluminate.3dspark.de/api/public/v1/parts/<part-id>/extract \
-H "Authorization: Bearer $VOLUMINATE_API_KEY"The upload response includes extraction. /extract returns 202 when it starts an extraction. Extraction takes a few minutes. Poll every 30–60 seconds until status is no longer pending. Asking again for a part that is already running or finished returns that extraction instead of starting a new one; only a failed extraction is started again.
curl https://voluminate.3dspark.de/api/public/v1/parts/<part-id>/extraction \
-H "Authorization: Bearer $VOLUMINATE_API_KEY"{
"extraction": {
"id": "…",
"status": "completed",
"requestedAt": "…",
"completedAt": "…",
"outdated": false,
"error": null,
"result": {
"schema_version": "drawing_extraction_v1",
"status": "completed",
"files": [ { "sourceFileId": "…", "fileName": "bracket.pdf", "category": "technical_drawing", "status": "completed", "errorCodes": [] } ],
"parts": [ {
"partIndex": 1,
"status": "completed",
"fields": {
"surface_finish": {
"value": "Ra 1.6 on the flange face",
"confidence": 0.7,
"semanticStatus": "extracted",
"estimatedValue": null,
…
},
…
}
} ]
}
}
}status is pending, completed, partial (some fields could not be read), failed or rejected (the file is not a usable drawing). Every part has all eleven fields. semanticStatus says whether a value was read from the drawing (extracted), estimated (estimated, value in estimatedValue), does not apply (not_applicable) or was not found (not_available). Estimates are never mixed into value. completed means the reading finished; it is not an engineering verification of the drawing.
The list fields (tolerances_gdt, surface_finish, threads_fits, heat_treatment, quality_inspection) can include items: one entry per callout as printed on the drawing, each with its sourceFileId. tolerances_gdt can include general, the general tolerance (e.g. ISO 2768-mK). If items is absent, use value.
"tolerances_gdt": {
"value": "General: ISO 2768-mK | Ø40 H7 bore, front view | 120 ±0.05 overall length",
"general": "ISO 2768-mK",
"items": [
{ "text": "Ø40 H7 bore, front view", "sourceFileId": "…" },
{ "text": "120 ±0.05 overall length", "sourceFileId": "…" }
],
"semanticStatus": "extracted",
…
}Errors
Errors return { "error": { "code", "message" } }. The message says what to do next.
400the request could not be carried out (request_failed)401missing, invalid or revoked API key402not enough credits for this part (insufficient_credits,no_credits,free_runs)403the account must first act in the app: verify its email (email_unverified) or complete its profile (qualification_required). Also returned for blocked accounts and company workspace accounts (company_api_not_enabled)404unknown part409the part needs a ready analysis first (analysis_required): call/convertagain422invalid request or files, or the part was not accepted (not_accepted)429hourly rate limit reached503analysis or extraction temporarily unavailable: retry later