Core Concepts: Files, Quotes and Jobs

1. Authentication & Security

Every endpoint requires authentication with your Quote3D API token, with one exception: the public upload route documented under File Management. For external calls, use the https://api.quote3d.com/v2 base route. Send the token either as Authorization: Bearer YOUR_TOKEN or X-API-Token. Generate tokens from your Quote3D dashboard and keep them secret.

Tokens can be scoped. A full-access token reaches every endpoint, while a widget-scoped token is restricted to the endpoints the embedded widget needs. Calling anything outside a token's scope returns 403. You can see and change a token's scope on the Tokens page of your dashboard.

2. Account Management

Manage your account, uploads, and usage statistics through dedicated endpoints:

• GET /v2/user Retrieve your account details, plan, and monthly allowances — this is where quotes_used, quotes_limit, storage_used, storage_limit and reset_date live
• GET /v2/user/uploads List all of the files you've uploaded to your account. These are listed from newest to oldest.
• GET /v2/quota Get your rate limit allowances — the global limit plus a per-endpoint breakdown with remaining calls and reset times — together with your request counts for today, this month, this year, and all time
• GET /v2/usage Get detailed usage analytics including endpoint statistics, material usage, and time-based trends

3. File Management

Upload, download, and manage your 3D model files (STL, 3MF, OBJ formats):

• GET /v2/file/upload-id — Get a temporary upload_id to upload a new file with the public upload route.
• POST /v2/file/public/{upload_id} — This route does NOT require authentication. Use this on your client side to upload files directly to our storage.

  Using the Public Upload route lets you avoid routing large files through your backend server. This prevents exposing your API token and reduces server load.

• POST /v2/file — Upload a file from your server side (requires authentication, use this when you want to upload from your backend)
• GET /v2/file/{file_id} — Download a file using its file_id
• DELETE /v2/file/{file_id} — Delete a file you no longer need

The upload is rejected if the file is not a valid STL, 3MF, or OBJ model, or if it exceeds the platform file size limit (50 MB by default). Both upload routes apply the same checks.

How your files are stored

Uploaded models are stored encrypted and are never publicly reachable — there is no link that serves a stored file directly. The file_path field in responses is the authenticated download path (GET /v2/file/{file_id}), not a location on disk, so treat it as an endpoint rather than a URL you can share. Deleting a file removes it from storage, not only from your listings.

4. Part Info & Technical Analysis

Check if your models are printable, get part dimensions, and advanced technical metrics:

• POST /v2/printability/{file_id} Instant Analysis - Check measurements, volume, surface area, and geometric integrity (open edges/non-manifold) before generating a quote.

Quote3D goes beyond simple dimension checks; it analyzes the model's manifold integrity and evaluates the bed adhesion risk critical for 3D printing. These metrics are provided in both Printability and Quote responses.

5. Quote Operations

Generate instant quotes for your 3D prints and manage quote history:

• POST /v2/file/quote/{file_id} — Start asynchronous quote calculation for a 3D model. Returns a job ID; use the jobs endpoint to retrieve the completed result.
• POST /v2/file/quote/{file_id}/async — Alternative asynchronous quote endpoint. Returns a job ID that you can use to check status and fetch the completed result.
• GET /v2/jobs/{job_id} — Check the status of an async quote job. Returns progress percentage and completion status.
• GET /v2/quotes — Retrieve all your quote history with pagination support
• GET /v2/quotes/{quote_id} — Get detailed information about a specific quote
• DELETE /v2/quotes/{quote_id} — Remove a quote from your history

Quote Request Parameters

When generating a quote, you can provide custom configuration in the request body. Any parameters you don't specify will be automatically taken from your Dashboard Slice Profile settings. This allows you to override specific settings per quote while keeping defaults for others.

The tables below cover the parameters integrations override most often. They are not the full list — the quote engine accepts many more printer, material, and pricing fields, and every one of them can be set once in your Dashboard Slice Profiles instead of being sent on each request. Configure your profiles there and send only what varies per quote; the complete field list lives in the OpenAPI schema.

Request Validation

Numeric fields in printer_config, material_config and quote_config are bound-checked before the job is queued. A value outside its range, a non-finite number (NaN, Infinity), a wrong type, or a negative number where only zero and above make sense is rejected with HTTP 400 and a VALIDATION_ERROR naming the exact field. Zero is still accepted wherever it is meaningful — a per-role speed or acceleration of 0 means "use the printer default", the same convention OrcaSlicer uses.

• Temperature limits: the material temperatures (temperature and bed_temperature, whether sent in the request or read from the Material Profile) are checked against the printer's min_hotend_temp / max_hotend_temp and min_bed_temp / max_bed_temp. A material that needs more heat than the selected printer can deliver is rejected instead of being quoted. FDM only — resin and powder technologies have no nozzle or heated bed. Leave the printer limits unset to skip the check.
• Enabled technologies: if you have restricted the technologies in your Global Settings, a quote request for a disabled technology is rejected. Leave the setting empty to accept all three.
• Material price fields: price_per_gram is the value the engine charges. When you save a Material Profile, price_per_kg is recalculated from it automatically (and price_per_gram is derived from price_per_kg when only the kilogram price is supplied), so the two can never disagree.

Root Parameters

Quantity and Batch Production Logic

Our system utilizes an advanced packing algorithm based on the specified 'quantity':

• FDM Technology: Parts are placed side-by-side on the build plate (X and Y axes) as space permits.
• SLA Technology: Parts are positioned side-by-side in the resin vat (X and Y axes).
• SLS Technology: Parts can be stacked in all axes (X, Y, and Z) to fully utilize the powder bed capacity.

printer_config

Printer configuration parameters. All fields are optional and will use your default Printer Profile values if not provided.

material_config

Material configuration parameters. All fields are optional and will use your default Material Profile values if not provided.

quote_config

Quote pricing configuration parameters. All fields are optional and will use your default Global Settings values if not provided. The currency defaults to your dashboard preference (e.g., 'USD', 'TRY', 'EUR').

6. Printer & Quote Profiles

Configure printer settings and pricing to get accurate quotes. You can manage your default profiles in the Dashboard Slice Profiles section, which will be used automatically when you don't specify parameters in API requests.

Profile Types

• Printer Profile - Configure your printer settings (bed size, nozzle diameter, print speed, layer height, acceleration, jerk, temperatures, etc.) to match your actual printer. Set this as your default profile in the Dashboard, and it will be used for all quote requests unless you override specific parameters.
• Material Profile - Set material properties (filament type, density, diameter, temperatures, fan speed, flow ratio, retraction settings, pricing) for each material you use. The API will automatically use the material profile matching the filament_type you specify in the request.
• Global Settings - Configure global quote settings like tax rate, fixed fees, energy costs, and default currency. These settings apply to all quotes unless overridden in the request.

How Profile Merging Works

When you make a quote request, the API merges your request parameters with your Dashboard profiles using this priority:

1. Request Parameters - Values you explicitly provide in the API request take highest priority
2. User Profile - If you have a user-specific profile set as default, it's used next
3. Global Profile - If no user profile exists, the system falls back to global defaults

This means you can override just the parameters you need (e.g., only layer_height or fill_density) while keeping all other settings from your Dashboard profiles.

7. Webhooks

Receive real-time notifications when events occur in your account:

• POST /v2/webhooks - Create a new webhook endpoint
• GET /v2/webhooks - List all your webhooks
• GET /v2/webhooks/{webhook_id} - Get webhook details and delivery statistics
• PUT /v2/webhooks/{webhook_id} - Update webhook settings
• DELETE /v2/webhooks/{webhook_id} - Remove a webhook

Supported events include: quote.completed, quote.failed, file.uploaded, file.deleted, job.status_changed, widget.added_to_cart. Webhooks include HMAC-SHA256 signatures for security verification.

Webhooks reference: payload shape, signature verification, retries and redelivery

8. Analytics & Reporting

Get insights into your API usage and quote statistics:

• GET /v2/analytics/quotes - Get comprehensive quote statistics including total quotes, average prices, material usage trends
• GET /v2/analytics/popular - See your most popular materials and printer configurations
• GET /v2/analytics/cost-trends - Analyze cost trends over time (daily, weekly, or monthly grouping)
• GET /v2/analytics/export - Export your quotes and usage data as CSV or JSON

9. Rate Limiting & Quotas

Quote3D uses rate limiting to ensure fair usage and system stability:

• Rate limits are applied per API token and vary by endpoint
• Rate limit information is included in response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-RateLimit-Window
• When rate limited, you'll receive a 429 Too Many Requests response with a Retry-After header
• Monthly quotas for quotes and storage are based on your subscription plan
• Limits are configurable per deployment, so read the current values rather than hard-coding them. Both the response headers above and this endpoint report them: GET /v2/quota

10. Responses & Errors

Every JSON response uses the same envelope. A successful call returns success: true with the endpoint's payload under data, so your client can read one consistent shape everywhere. File downloads and CSV exports are the exception — they return the raw file body instead of the envelope.

{
  "success": true,
  "data": { "...": "endpoint-specific payload" }
}

Pagination & Sorting

List endpoints such as /v2/quotes and /v2/user/uploads are paginated with the limit and offset query parameters (default 50 results, maximum 100). Alongside the results they return a pagination object holding total, limit, offset, has_more, page and total_pages, so prefer has_more over recomputing the end of the list yourself. Sorting uses a single repeatable parameter in field:direction form, for example ?sort=created_at:desc&sort=total_price:asc; uploads default to newest first.

Error Responses

Failures return success: false with a human-readable error message and the matching HTTP status code. Always branch on the status code rather than on the message text, which may be reworded.

Asynchronous quotes are different: queueing the job succeeds with 202, and a calculation that fails afterwards surfaces as a failed status with an error message on the job endpoint — not as an HTTP error. Always inspect the job status, not just the status code you got when you started it.

11. RESTful, Versioned API

• All endpoints are versioned (e.g., /v2/)
• Uses standard HTTP methods: GET, POST, PUT, DELETE
• Described by an OpenAPI 3.0.3 schema you can import into your own tooling
• Breaking changes and additions are recorded in the API changelog