Welcome to the Quote3D Documentation!
Quote3D LogoQuote3DDocumentation

LLM and AI Agent Integration Guide

This page provides contextual instructions specifically designed to be read by Large Language Models (LLMs) like GPT-4, Claude, or Gemini. You can feed this page directly to your AI assistant to help it quickly integrate the Quote3D API into your project.

System Prompt

Use the text below to explain Quote3D's architecture to your AI assistant or code generation tool (Copilot):

You are integrating Quote3D: a REST API for instant 3D-printing quotes, with async quote jobs, webhooks, and an embeddable storefront widget. Follow this contract exactly. Where it contradicts your prior assumptions about quoting APIs, this contract wins.

== 0. TRANSPORT AND ENVELOPE ==
Base URL: https://api.quote3d.com — all paths are versioned under /v2.
Every JSON response uses one envelope: { "success": true, "data": { ... } } on success, and { "success": false, "error": "message" } on failure. File downloads and CSV exports return the raw body instead.
Branch on the HTTP status code, never on the error text — messages get reworded.

== 1. AUTHENTICATION ==
Send the token as 'Authorization: Bearer TOKEN' or 'X-API-Token: TOKEN'. Pick one style and use it consistently.
Tokens are opaque credentials — do not parse them, and do not depend on their internal structure.
Exactly one endpoint needs no authentication: the public upload route in section 2.
Token scopes: a token is either full-access or widget-scoped. A widget-scoped token only reaches what the embedded widget needs; everywhere else it is rejected with 403. Use a full-access server token for webhooks, analytics, usage and quota.
A token may also be restricted to an IP allowlist and may carry an expiry. Both failures surface as 403 and 401 respectively, not as a network error.

== 2. UPLOADING A MODEL ==
Accepted formats: STL, 3MF, OBJ. Uploads above the platform limit (50 MB by default) are rejected.
There are two upload paths. Choose deliberately.
(a) Server-side: POST /v2/file, multipart/form-data, field name 'file', authenticated. Use when the file already sits on your backend.
(b) Browser-direct, two steps: GET /v2/file/upload-id returns data.upload_id, valid for one hour. Then POST /v2/file/public/{upload_id} with multipart field 'file' and NO Authorization header. Prefer this when the shopper's browser holds the file — it keeps large uploads off your server and keeps your token out of client code.
Both paths return a file_id. Keep it; every later call is keyed on it.
File management: GET /v2/file/{file_id} downloads, DELETE /v2/file/{file_id} removes, GET /v2/user/uploads lists (newest first).
Responses carry file_path, which is the authenticated download path (/v2/file/{file_id}) — not a location on disk. Uploads are never reachable as static files, so there is no URL to link to directly.

== 3. OPTIONAL PRE-CHECK ==
POST /v2/printability/{file_id} answers synchronously with dimensions, volume, surface_area and geometric integrity (is_valid, open_edges, non_manifold_edges). Use it to reject unprintable models before spending a quote.
It needs build-volume dimensions: it reads them from the selected printer profile, or you pass x, y and z in the body. If neither is available it returns 400. The body also accepts technology.

== 4. QUOTING IS ASYNCHRONOUS — THIS IS THE PART MOST INTEGRATIONS GET WRONG ==
POST /v2/file/quote/{file_id} does NOT return a price. It answers 202 Accepted with { jobId, status: 'queued', statusUrl, estimatedTime, createdAt }.
POST /v2/file/quote/{file_id}/async is the same endpoint under a second name. Do not build different logic for the two.
Request body, all optional: technology ('FDM' | 'SLA' | 'SLS'; 'RESIN' is an alias for 'SLA'), printer_id, quantity, and the three config objects printer_config, material_config and quote_config.
Anything you omit is resolved for you: request value first, then the user's dashboard profile, then the global profile. So the minimal useful body is often {} or { "quantity": 2 }. Do not invent required fields, and do not send a wall of parameters an integrator would rather configure once in their dashboard.
Then poll GET /v2/jobs/{job_id} and read data.status. Statuses are LOWERCASE: 'queued', 'processing', 'completed', 'failed', 'cancelled'. Terminal statuses are 'completed', 'failed' and 'cancelled'.
A failed calculation still answers HTTP 200, with status 'failed' and data.error = { message, code }. Never treat 200 as success — inspect data.status. This is the single most common bug in generated Quote3D clients.
While processing you may also read data.progress and data.estimatedTimeRemaining. On completion the quote payload is at data.result.
Poll with a bounded loop: a fixed 2-3 second interval or exponential backoff, plus a hard attempt cap and a timeout path. Never poll without a ceiling.

== 5. READING STORED QUOTES ==
GET /v2/quotes lists them, GET /v2/quotes/{quote_id} returns one, DELETE /v2/quotes/{quote_id} removes one.
Pagination: limit and offset query parameters, default 50, maximum 100. The response carries a pagination object with total, limit, offset, has_more, page and total_pages — use has_more rather than computing the end yourself.
Sorting is one repeatable parameter in field:direction form, e.g. ?sort=created_at:desc.
Caveat: the detailed 'result' block on a stored quote is a stored payload, and older or partial records fall back to a smaller shape holding only pricing.total, pricing.currency, timeEstimation and modelInfo. Read defensively with optional chaining instead of assuming the rich shape.

== 6. WEBHOOKS — THE PRODUCTION PATTERN ==
Prefer webhooks over polling for anything long-lived.
Manage them with POST /v2/webhooks (body: { url, events }), GET /v2/webhooks, GET/PUT/DELETE /v2/webhooks/{webhook_id}, and POST /v2/webhooks/{webhook_id}/deliveries/{delivery_id}/resend to redeliver.
The signing secret is returned ONLY in the create response. Store it immediately; it cannot be read back.
Event catalogue, exhaustively: 'quote.completed', 'quote.failed', 'file.uploaded', 'file.deleted', 'job.status_changed', 'widget.added_to_cart'.
Verification: compute HMAC-SHA256 over the RAW request body with the secret and compare against the 'X-Webhook-Signature' header, whose value is the literal prefix 'sha256=' followed by the hex digest. Use a timing-safe comparison. The event name also arrives in 'X-Webhook-Event'.
Read the raw body before any JSON body parser touches it, or the signature will never match.
Deliveries retry, so handlers must be idempotent — key on the event id or the quote id, and make repeat delivery a no-op.

== 7. THE EMBEDDABLE WIDGET ==
Load /js/quote3d-embed.js, then Quote3D.init('#root', { token, theme, color, locale, redirectUrl, quoteId, onResult, onAddToCart }). There is also a baseUrl option, which defaults to the origin serving the script.
The SDK builds an iframe URL and maps redirectUrl to the query parameter 'redirect_url'.
Give the widget a widget-scoped token, never a full-access one — it is visible in client code.
The iframe posts three message types to the host: 'QUOTE3D_RESULT', 'QUOTE3D_ADD_TO_CART' and 'QUOTE3D_RESIZE'. Handle resize by setting the iframe height; ignoring it leaves the widget clipped.
Payload contract: quoteId, price, unitPrice, currency, material, color, technology, quantity, fileName, weight, filamentWeight, estimatedTime, dimensions, and print settings such as layerHeight, infill, infillPattern, walls, postProcessing, hollowing.
The total is 'price'. There is NO 'totalPrice' field — reading it yields undefined and silently breaks carts.
The add-to-cart payload adds thumbnail, thumbnailUrl, thumbnailBase64 and addedAt. Keep handling both weight and filamentWeight for backward compatibility.
thumbnailUrl is an absolute, signed URL that renders from any origin — store it as given and never rewrite or re-host it, or the image stops resolving.
Do not call the widget's own internal routes from your code. To react to a shopper adding a configured part to the cart, subscribe to the 'widget.added_to_cart' webhook.

== 8. ACCOUNT, LIMITS AND REPORTING ==
GET /v2/user — account, plan and monthly allowances: quotes_used, quotes_limit, storage_used, storage_limit, files, days_till_reset, reset_date.
GET /v2/quota — rate-limit allowances (global plus a per-endpoint breakdown with remaining and reset times) and request counts for today, this month, this year and all time.
GET /v2/usage — usage analytics including per-endpoint and per-material statistics.
GET /v2/analytics/quotes (period=day|week|month|year|custom, with date_from and date_to when custom), /v2/analytics/popular (limit, default 10), /v2/analytics/cost-trends (group_by=day|week|month), /v2/analytics/export (format=json|csv).

== 9. ERRORS AND RESILIENCE ==
400 — invalid body or query, unsupported format, or a model that does not fit the selected printer.
401 — token missing, malformed, expired or revoked.
403 — valid token, not permitted: scope restriction or IP allowlist.
404 — the file, quote, job or webhook does not exist or belongs to another account.
429 — rate limited. Read the 'Retry-After' header and back off exponentially.
500 — retry with backoff; if it persists, surface the timestamp to the user.
Rate-limit state also arrives on successful responses via 'X-RateLimit-Limit', 'X-RateLimit-Remaining', 'X-RateLimit-Reset' and 'X-RateLimit-Window'. Limits are configurable per deployment, so read them from these headers or from GET /v2/quota — never hardcode a number.

== 10. DO NOT DO THESE ==
- Do not expect a price from the quote endpoint, and do not add a 'wait' that assumes the job finished.
- Do not compare job status against uppercase strings.
- Do not treat HTTP 200 on the jobs endpoint as success.
- Do not read 'totalPrice' from a widget payload.
- Do not put a full-access token in browser code, an iframe URL, a query string or a redirect payload.
- Do not JSON-parse the webhook body before computing its signature.
- Do not hardcode rate limits, quota numbers or the file-size cap.
- Do not invent endpoints, fields or query parameters. If this contract does not name it, ask instead of guessing.

== WHAT TO PRODUCE ==
- Complete upload -> optional printability check -> async quote -> bounded polling -> result flows.
- Widget embed code with resize handling, redirect handling and postMessage listeners.
- Add-to-cart bridges that preserve the payload fields above and read 'price'.
- Webhook handlers with raw-body signature verification, timing-safe comparison and idempotent processing.
- Error handling that distinguishes 400/401/403/404/429/500 and honours Retry-After.

LLM Context for Widget Integration

You can ask your LLM assistant to perform these widget-related tasks:

  • JS SDK Configuration: Generate a Quote3D.init setup that uses token, locale, theme, color, optional quoteId, and redirectUrl.
  • Event Listening: Write host-page listeners for QUOTE3D_RESULT, QUOTE3D_ADD_TO_CART, and QUOTE3D_RESIZE.
  • Payload Mapping: Persist the returned quote payload fields such as quoteId, price, unitPrice, currency, technology, quantity, thumbnailUrl, fileName, weight, and filamentWeight. Note the total is price, not totalPrice.

Webhook Processing Logic

Provide these details to have your bot write webhook security and event handling code:

  • Signature Verification: Write functions to verify the X-Webhook-Signature header using HMAC-SHA256 over the raw request body. The header value is the literal prefix sha256= followed by the hex digest, so compare it with a timing-safe comparison rather than a plain equality check.
  • Event Handling: Manage the full event catalogue - quote.completed, quote.failed, file.uploaded, file.deleted, job.status_changed and widget.added_to_cart - with idempotent handlers.

Best Practices for Agents

When writing integration code for Quote3D, always handle the following:

  • Implement asynchronous polling for quote generation. Do not expect immediate price returns from the initial quote creation request.
  • Use a bounded polling loop with exponential backoff or a fixed 2-3 second delay when checking /v2/jobs/{job_id}.
  • Preserve both weight &filamentWeight in cart or order metadata to stay compatible with current widget payloads and plugins.
  • Prefer webhooks for production integrations, and make handlers idempotent because retries can happen.

Critical Endpoints Summary

A quick reference index of the most used endpoints required for basic implementation:

Upload File (server-side): POST /v2/file
Upload File (browser-direct, no token in client code): GET /v2/file/upload-id → POST /v2/file/public/{upload_id}
Pre-check Printability: POST /v2/printability/{file_id}
Start Quote: POST /v2/file/quote/{file_id}
Check Status: GET /v2/jobs/{job_id}
Read Async Job Result: job.result
Get Quote History: GET /v2/quotes
Subscribe to Events: POST /v2/webhooks
Allowances and Rate Limits: GET /v2/user, GET /v2/quota

End-to-End Integration Flow

The order the API expects, and what each step hands to the next. Ask your assistant to implement these six steps rather than describing an endpoint in isolation — most integration bugs come from skipping a step or assuming the wrong handoff.

  1. Create a token in the dashboard and choose its scope: full access for your server, widget scope for anything embedded in a storefront.
  2. Get the model into Quote3D and keep the returned file_id. Upload from your backend with POST /v2/file, or let the browser upload directly with GET /v2/file/upload-id followed by POST /v2/file/public/{upload_id} — the second path keeps large files off your server and your token out of client code.
  3. Optionally pre-check the model with POST /v2/printability/{file_id} to reject unprintable geometry before it costs you a quote.
  4. Start the quote with POST /v2/file/quote/{file_id}. It answers 202 with a jobId, not a price. Send only the parameters that vary per quote; everything else resolves from the dashboard profiles.
  5. Wait for the result. In production, subscribe to the quote.completed and quote.failed webhooks. For scripts and prototypes, poll GET /v2/jobs/{job_id} in a bounded loop until the status is completed, failed or cancelled.
  6. Read the result from the job payload, or later from GET /v2/quotes and GET /v2/quotes/{quote_id}. Handle 429 by honouring Retry-After throughout.

The three mistakes that account for most broken integrations: expecting a price from the quote endpoint, comparing job status against uppercase strings, and treating HTTP 200 on the jobs endpoint as success when the job actually failed. The system prompt above states all three explicitly so your assistant does not reproduce them.