Developer docs · API v1

Vertessia API

Base URL https://vertessia.com/v1 · JSON over HTTPS · Updated 7 November 2026

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.

What reconstruction gives you: fitted NURBS surfaces (Organic) or planes, cylinders and cones (Mechanical) as a STEP solid or surface body. It does not recover a parametric feature tree. Every result comes with a deviation report; check it before you use the part.

Quick start

  1. Create an API key on your account page. It is shown once; store it like a password.
  2. Accept the Terms for your account once (see Terms).
  3. 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

FieldDescription
fileRequired. .stl .obj .ply .3mf .glb .gltf .step .stp, up to 100 MB. A .gltf must have its buffers embedded (or send .glb).
targetstep (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.
surfaceMesh → 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_sizeOrganic 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).
unitmm, 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_sizeSTEP → mesh only: tessellation fineness. Optional; clamped to safe ranges.
callback_urlOptional https URL that receives a signed POST when the job finishes (Webhooks). Requires authentication.
accept_termsCurrent Terms version, unless your account already accepted it.
retain1 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

EndpointDescription
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/jobsYour recent jobs (?limit= up to 200).
GET/v1/jobs/{id}/eventsServer-sent events with the same JSON as the status, once per second until the job ends.
GET/v1/jobs/{id}/previewFree STL preview of the result (for STEP results a tessellation of the reconstructed surfaces).
POST/v1/jobs/{id}/download-linkCharges 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}/downloadDownload with your key directly (same charging rule, same ?part= values), or with the ?t= link above without a key.
GET/v1/meAccount, credit balance, plan quota, accepted Terms version and your api limits.
GET/v1/configFormats, 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 hourReconstructions running at onceReconstructions per day
Free account (no purchase yet)6015
Credits purchased60120
Maker1201100
Pro3002300
Team100041000

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"}

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.

CodeMeaningWhat to do
400Unsupported format or conversion, Terms not accepted, invalid callback_url.Fix the request; the message says what is wrong. Retrying unchanged will not help.
401Missing, invalid or revoked key; reconstruction or callback_url without authentication.Check the key.
402Not enough credits for a billable download.Buy credits or a plan; the result stays available for 24 hours.
403The 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.
404Job not found or expired (results are kept 24 hours, paid STEP 30 days).Convert again.
409Job not finished yet; Idempotency-Key reused with other parameters, or still being processed.Wait for done; use a new key for a different request.
413File larger than 100 MB.Simplify the mesh first (for example with our free STL simplifier).
429Request 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.
503The 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.

Questions, higher limits or something missing? info@vertessia.com