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. Create personal keys on your Account page; company owners and admins create company keys in Company settings. Parts created with a personal key belong to its account. A company key creates parts in its company workspace, which are paid from the company's credits.
Authorization: Bearer vlm_ab12cd34_...Limits
Up to 5 active keys per account, and up to 5 per company. Every 24 hours, an account can create 50 new parts and start 20 drawing extractions through the API. For company keys these limits are shared by the whole company. Conversions are charged in credits exactly as in the app.
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.
A part is converted once, as in the app. After its conversion has started, /convert returns that conversion whatever its status, and nothing new is started or charged.
Once the analysis is ready, analysis.price.credits shows what the conversion will cost in credits. analysis.price.freeFirstRun is true when it is the account's free first conversion; the price is then 0. analysis.price is null once the part has a conversion.
"analysis": { "status": "ready", "message": null, "price": { "credits": 120, "freeFirstRun": false } }To never pay more than you expect, send { "maxPrice": 120 } with your second call to /convert. A higher price is refused with 409 price_above_max and nothing is charged.
curl -X POST https://voluminate.3dspark.de/api/public/v1/parts/<part-id>/convert \
-H "Authorization: Bearer $VOLUMINATE_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "maxPrice": 120 }'202 Accepted (analysis running)
{ "conversion": null, "analysis": { "status": "pending" } }
200 OK (conversion started)
{ "conversion": { "id": "…", "status": "queued" } }
409 Conflict (price above maxPrice, nothing charged)
{ "error": { "code": "price_above_max", "message": "This part costs 150 credits, more than your maxPrice of 120. No conversion was started." } }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.
conversion describes the newest run. models come from the newest completed run you have paid for, an Engineer Built model first, and modelsConversionId names that run. A newer run that is still processing or has failed does not hide models you already have.
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, "price": null },
"conversion": { "id": "…", "status": "completed", "createdAt": "…", "completedAt": "…" },
"models": [
{ "id": "variant-1", "format": "stl", "sizeBytes": 812344, "downloadUrl": "https://…" }
],
"modelsConversionId": "…"
}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, for personal keys of company workspace accounts (company_key_required), and for company keys whose creator lost their company or workspace role (key_access_revoked,workspace_access_denied)404unknown part409the part needs a ready analysis first (analysis_required): call/convertagain409the price is above yourmaxPrice(price_above_max); nothing was charged422invalid request or files, or the part was not accepted (not_accepted)429hourly conversion limit reached (rate_limit), or daily API limit reached (daily_limit, with aRetry-Afterheader)503analysis or extraction temporarily unavailable: retry later