Vertessia API
The same conversions as the website, from your own scripts and plug-ins: mesh → editable STEP (surface reconstruction) and free conversions between STL, OBJ, PLY, 3MF, GLB, glTF and STEP. Jobs run asynchronously: you upload a file, get a job id, then wait (poll or webhook) and download.
Quick start
- Create an API key on your account page. It is shown once; store it like a password.
- Accept the Terms for your account once (see Terms).
- Submit, wait, download:
export VERTESSIA_API_KEY=vk_live_...
# 1. submit
curl -s https://vertessia.com/v1/convert \
-H "Authorization: Bearer $VERTESSIA_API_KEY" \
-F file=@part.stl -F target=step -F surface=nurbs
# → {"job_id":"9f2c…","access_token":"…","status":"queued","waiting":false,"billable":true,…}
# 2. poll until status is "done" or "error"
curl -s https://vertessia.com/v1/jobs/9f2c… -H "Authorization: Bearer $VERTESSIA_API_KEY"
# 3. get a 10-minute download link (a STEP download is charged here), then fetch it
curl -s -X POST https://vertessia.com/v1/jobs/9f2c…/download-link -H "Authorization: Bearer $VERTESSIA_API_KEY"
# → {"url":"/v1/jobs/9f2c…/download?t=…","expires_in":600,"filename":"part.step"}
curl -o part.step "https://vertessia.com/v1/jobs/9f2c…/download?t=…"
Authentication
Send Authorization: Bearer vk_live_… on every request. Keys act for your account: STEP downloads use your credits or plan quota. You can have up to 20 active keys and revoke any of them on the account page; a revoked key stops working at once.
Optional: send X-Vertessia-Client: my-plugin/1.2 (letters, digits and . _ / + -, up to 48 characters) so your integration shows up separately in our statistics.
Terms of Service
Every conversion requires acceptance of the current Terms of Service and output disclaimer. Either accept once for the account:
curl -s https://vertessia.com/v1/me/accept-terms \
-H "Authorization: Bearer $VERTESSIA_API_KEY" -H "Content-Type: application/json" \
-d '{"version":"2026-09-28"}'
or send accept_terms=<version> with each /convert. The current version is terms_version in GET /v1/config; GET /v1/me shows the version your account accepted (terms_version) next to the current one (terms_current). When the Terms change, the version changes and you must accept again — until then /convert answers 400 with instructions.
POST /v1/convert
POST/v1/convert · multipart/form-data
| Field | Description |
|---|---|
file | Required. .stl .obj .ply .3mf .glb .gltf .step .stp, up to 100 MB. A .gltf must have its buffers embedded (or send .glb). |
target | step (reconstruction, from any mesh), stl obj ply 3mf glb gltf (free conversions; from a STEP file it tessellates), drawing (from a STEP file: a 2D reference drawing, PDF as the result and DXF with ?part=drawing_dxf; one credit, like a reconstruction). Default: STEP for meshes, STL for STEP files. |
surface | Mesh → STEP only. nurbs (Organic: scans, sculptures, teeth, AI models; default) or smooth (Mechanical: planes, cylinders, cones). If Mechanical fitting fails the engine falls back to faceted surfaces, marked surface: "facet" in the metrics; facet results are free to download. |
patch_size | Organic patch edge length in mm, 0.2–50, default 1. For large models use larger patches — about model size ÷ 150 works well (e.g. 16 mm for a 2.4 m model). Very small patches on large models are raised automatically (they would run out of memory or time). |
unit | mm, m or in — the unit of the input file. Default: metres for GLB/glTF, millimetres for everything else. |
edge_size, angle_size, min_edge_size, max_edge_size | STEP → mesh only: tessellation fineness. Optional; clamped to safe ranges. |
callback_url | Optional https URL that receives a signed POST when the job finishes (Webhooks). Requires authentication. |
accept_terms | Current Terms version, unless your account already accepted it. |
retain | 1 lets us keep the upload to improve the engine. Default 0: the upload is deleted after conversion. |
Headers: Idempotency-Key (below), X-Vertessia-Client. Response:
{"job_id": "9f2c…", "access_token": "…", "status": "queued", "waiting": false,
"operation": "stl2step", "target": "step", "billable": true}
waiting: true means you already have as many reconstructions running as your plan allows; the job sits in your personal waiting list and starts by itself when one finishes. reused: true means you submitted the same file with the same settings within 24 hours and got the earlier job back. Every /convert response carries X-RateLimit-Limit and X-RateLimit-Remaining.
Jobs and download
| Endpoint | Description |
|---|---|
| GET/v1/jobs/{id} | Status: status (queued processing done error), progress 0–100, message, metrics (faces, surface type, deviation with mean / p95 / max mm and coverage %), error_class on failure. |
| GET/v1/jobs | Your recent jobs (?limit= up to 200). |
| GET/v1/jobs/{id}/events | Server-sent events with the same JSON as the status, once per second until the job ends. |
| GET/v1/jobs/{id}/preview | Free STL preview of the result (for STEP results a tessellation of the reconstructed surfaces). |
| POST/v1/jobs/{id}/download-link | Charges a billable result (1 credit, or 1 from your plan's monthly quota; the same job is never charged twice) and returns a link valid for 10 minutes. Paid STEP files stay downloadable for 30 days. Add ?part=drawing_pdf or ?part=drawing_dxf for the 2D reference drawing of a CAD-part (surface=smooth) result: it is unlocked by the same charge as the STEP (has_drawing in the job status says whether there is one). |
| GET/v1/jobs/{id}/download | Download with your key directly (same charging rule, same ?part= values), or with the ?t= link above without a key. |
| GET/v1/me | Account, credit balance, plan quota, accepted Terms version and your api limits. |
| GET/v1/config | Formats, targets, current Terms version, upload limit. |
Mesh-to-mesh and STEP-to-mesh conversions are free. Only the STEP from a reconstruction is billable, and only when you download it: a failed or incomplete reconstruction is never charged. Results are deleted after 24 hours unless paid.
Jobs created without a key or login return an access_token; pass it as ?k= to the job endpoints. With a key you do not need it.
Limits
| Plan | /convert requests per hour | Reconstructions running at once | Reconstructions per day |
|---|---|---|---|
| Free account (no purchase yet) | 60 | 1 | 5 |
| Credits purchased | 60 | 1 | 20 |
| Maker | 120 | 1 | 100 |
| Pro | 300 | 2 | 300 |
| Team | 1000 | 4 | 1000 |
- Request limits count per account, not per key. Requests without a key are limited per IP address.
- With an API key, reconstructions above your concurrency wait in a personal list (up to 200 jobs) instead of being refused. A job that has waited 20 hours without starting is cancelled with status
error(not charged; uploads are deleted within 24 hours) — submit it again. Without a key (website login) a second concurrent job gets 429. - Large STEP tessellations (over 20 MB) and server deep repairs run one at a time per account.
- Your current values are in
GET /v1/me→api.
Idempotent retries
Send Idempotency-Key: <any string up to 255 characters> with /convert (authenticated requests only). For 24 hours the same key returns the same job_id and access_token with idempotent_replay: true, without uploading again and without counting against your request limit. Using the key with a different file name or different parameters returns 409; so does a retry while the first request is still being processed (wait a moment and retry). If the first request failed, or the job it created later failed or expired, the key is released: retrying with it starts a new job.
A good key is a hash of the file contents and your settings, which is what the Python client does.
Webhooks
Pass callback_url=https://… with /convert. When the job reaches done or error we POST JSON to it, once per job:
POST /your/hook
Content-Type: application/json
X-Vertessia-Event: job.done (or job.error)
X-Vertessia-Delivery: 5d0c… (same value on every retry of this delivery)
X-Vertessia-Signature: t=1762500000,v1=3f1a…
{"event":"job.done","job_id":"9f2c…","status":"done","operation":"stl2step","output_ext":"step",
"billable":true,"error_class":"","message":"Done",
"metrics":{"faces":8190,"surface":"nurbs","deviation":{"mean_mm":0.006,"p95_mm":0.019,"max_mm":0.85,"coverage_pct":100.0}},
"created_at":1762499880,"finished_at":1762500000,
"status_url":"https://vertessia.com/v1/jobs/9f2c…","download_link_url":"https://vertessia.com/v1/jobs/9f2c…/download-link"}
- The body contains no download token: call
download_link_urlwith your API key. - Answer with any 2xx within 10 seconds. Other answers and timeouts are retried 5 times (after about 10 s, 1 min, 5 min, 30 min and 1 h). Redirects are not followed.
- The URL must be https on a public address (no private, loopback or link-local IPs), at most 2048 characters. It is checked when you submit and again before every delivery.
- Your signing secret is on the account page (one per account; you can rotate it there). Verify every request and reject timestamps older than five minutes:
Verify in Python
import hashlib, hmac, time
def verify(body: bytes, header: str, secret: str, tolerance=300) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
t, sig = parts.get("t", ""), parts.get("v1", "")
expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, sig) and abs(time.time() - int(t)) <= tolerance
# Flask: verify(request.get_data(), request.headers["X-Vertessia-Signature"], SECRET)
Verify in Node.js
const crypto = require("crypto");
function verify(rawBody, header, secret, tolerance = 300) {
const parts = Object.fromEntries(header.split(",").map(p => p.split("=", 2)));
const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.`).update(rawBody).digest("hex");
const ok = expected.length === (parts.v1 || "").length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
return ok && Math.abs(Date.now() / 1000 - Number(parts.t)) <= tolerance;
}
// Express: app.post("/hook", express.raw({ type: "application/json" }), (req, res) => {
// if (!verify(req.body, req.get("X-Vertessia-Signature"), SECRET)) return res.sendStatus(400);
// res.sendStatus(204); /* then handle JSON.parse(req.body) */ });
Sign over the raw request body exactly as received; parsing and re-serialising the JSON changes it.
Errors
Errors are JSON {"detail": "…"} with a human-readable message.
| Code | Meaning | What to do |
|---|---|---|
| 400 | Unsupported format or conversion, Terms not accepted, invalid callback_url. | Fix the request; the message says what is wrong. Retrying unchanged will not help. |
| 401 | Missing, invalid or revoked key; reconstruction or callback_url without authentication. | Check the key. |
| 402 | Not enough credits for a billable download. | Buy credits or a plan; the result stays available for 24 hours. |
| 403 | The job belongs to another account, its result was already downloaded with another account, or a key was used where only a website login is accepted (managing keys and the webhook secret). | Use the right account. |
| 404 | Job not found or expired (results are kept 24 hours, paid STEP 30 days). | Convert again. |
| 409 | Job not finished yet; Idempotency-Key reused with other parameters, or still being processed. | Wait for done; use a new key for a different request. |
| 413 | File larger than 100 MB. | Simplify the mesh first (for example with our free STL simplifier). |
| 429 | Request limit, daily reconstruction limit, concurrency (website login) or waiting list full. | Wait for Retry-After seconds (sent for the hourly limit), or for running jobs to finish. |
| 503 | The reconstruction queue is full right now. | Retry after a few minutes with exponential backoff. |
A job that fails has status: "error", an error_class (for example bad_input, timeout, out_of_memory, incomplete, wrong_unit) and a message explaining what to try. Failed jobs are never charged.
Python client
A single file using only the standard library: vertessia_client.py (Python 3.9+). It submits with an automatic Idempotency-Key (re-running after a crash returns the same jobs), backs off on 429/503, waits and downloads.
# command line
export VERTESSIA_API_KEY=vk_live_...
python vertessia_client.py accept-terms --yes
python vertessia_client.py convert ./scans/*.stl --to step --surface organic --out ./out
python vertessia_client.py me
# library
from vertessia_client import Client
c = Client(api_key="vk_live_...", client_name="my-pipeline/1.0")
for path in ["a.stl", "b.stl"]:
status, step_file = c.convert_and_download(path, "./out", target="step", surface="organic")
print(path, status["status"], step_file, status["metrics"].get("deviation"))
surface accepts organic / mechanical (the website's names) or nurbs / smooth.
Working in Blender? The Vertessia add-on for Blender wraps the same API: import STEP files and send selected objects to STEP from the sidebar.