Developer API Guide - 3D Print Price Estimator

Introduction

Welcome to the 3D Print Price Estimator Developer API. This API allows external platforms, automation tools, and websites to calculate detailed print price estimates by directly uploading .stl or .3mf model files.

Endpoint Reference

POST /api/estimate/upload

Estimates slicing specifications (weight, time, color presets, dimensions) and computes bulk-optimized cost details in a single request. Content must be transmitted as multipart/form-data.

Form Fields (Request Body)

Field Name	Type	Required	Default	Description
`file`	File	Yes	-	The binary `.stl` or `.3mf` model file (Max 15MB).
`qty`	Integer	No	`1`	Quantity of prints to calculate bulk capacity plate-sharing on.
`timeRate`	Float	No	`50`	Hourly printer operational rate.
`weightRate`	Float	No	`2`	Filament material cost per gram.
`plateFee`	Float	No	`20`	Setup charge applied per build plate run.
`multicolorFee`	Float	No	`30`	Fee added per active AMS filament swap cycle.
`labourFee`	Float	No	`0`	Flat labor/handling charge.
`profitMargin`	Float	No	`0`	Profit margin percentage added on top of subtotal.
`roundingFactor`	Float	No	`10`	Rounding increments (e.g. round cost to nearest 10).
`currencySymbol`	String	No	`"Rs."`	Currency symbol used in the formatted formula.
`notify`	Boolean	No	`false`	Triggers Gotify message delivery if server is configured.

Authentication & Limits

To ensure platform stability and protect computing resources, the following policies are actively enforced:

IP Rate Limiting: Enforces a maximum of 5 file uploads per minute per IP address. Exceeding this rate limits requests temporarily.
Upload File Limits: Files must not exceed 15MB.
API Key (Optional): If the administrator has secured the server by populating the environment variable API_KEY, requests must contain credentials.

Configuring Authentication Headers

You can authenticate using either standard header type:

Authorization: Bearer YOUR_API_KEY
# OR
X-API-Key: YOUR_API_KEY

HTTP Response Status Codes

Status Code	Name	Trigger Condition
`200`	OK	The file was successfully parsed and estimates computed.
`400`	Bad Request	Missing files, invalid file extensions, or bad form parameters.
`401`	Unauthorized	API key authentication failed or request header is missing credentials.
`413`	Payload Too Large	The uploaded file exceeds the 15MB maximum allowed threshold.
`429`	Too Many Requests	Exceeded the sliding-window threshold of 5 request uploads per minute.
`500`	Internal Error	Corrupted files, ZIP archive processing, or geometry parsing failure.

Code Examples

cURL Upload Request

curl -X POST http://localhost:3000/api/estimate/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/my_model.stl" \
  -F "qty=3" \
  -F "timeRate=60" \
  -F "weightRate=3.5"

JavaScript Fetch

const fileInput = document.querySelector('input[type="file"]');
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('qty', '5');
formData.append('timeRate', '50');

fetch('https://your-domain.com/api/estimate/upload', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY' // if configured
  },
  body: formData
})
.then(response => response.json())
.then(data => {
  if (data.success) {
    console.log(`Estimated Cost: ${data.pricing.currencySymbol} ${data.pricing.estimatedCost}`);
    console.log(`Weight: ${data.parsedData.weightGrams}g`);
  } else {
    console.error('Calculation Error:', data.error);
  }
})
.catch(err => console.error('Network Error:', err));

Sample Response Payload

{
  "success": true,
  "filename": "my_model.stl",
  "type": "STL",
  "parsedData": {
    "weightGrams": 45.2,
    "printTimeHours": 1.25,
    "printTimeSeconds": 4500,
    "widthMm": 50.5,
    "lengthMm": 45.0,
    "heightMm": 22.0,
    "filaments": [
      {
        "type": "PLA",
        "color": "#10b981",
        "usedG": 45.2,
        "name": "PLA Basic Green",
        "multiplier": 1
      }
    ],
    "plates": [],
    "isFromMetadata": false
  },
  "pricing": {
    "qty": 1,
    "rates": {
      "timeRate": 50,
      "weightRate": 2,
      "plateFee": 20,
      "multicolorFee": 30,
      "labourFee": 0,
      "profitMarginPct": 0,
      "roundingFactor": 10
    },
    "singleUnit": {
      "timeCost": 62.5,
      "materialCost": 90.4,
      "plateCost": 0,
      "hardwareCost": 0,
      "cost": 152.9
    },
    "totalPrintTimeHours": 1.25,
    "totalPlatesRun": 1,
    "plateCost": 0,
    "totalMulticolorCost": 0,
    "totalMaterialCost": 90.4,
    "totalTimeCost": 62.5,
    "totalHardwareCost": 0,
    "subtotal": 152.9,
    "labourFee": 0,
    "profitAmount": 0,
    "rawCost": 152.9,
    "estimatedCost": 160,
    "currencySymbol": "Rs.",
    "formula": "1 unit(s) · 1.25h total print time · Max 4 per plate
1.25h × Rs.50/hr + 45.2g × Rs.2/g = Rs. 160",
    "activeHardware": [],
    "savings": 0
  }
}