Docs

The Mint Motive API

Two APIs on one engine. The Engine API turns settings into print-ready models: Gridfinity bins, baseplates, holders, label clips, Skådis parts and Deck Foundry parts, as STL, 3MF or OBJ. The Tracer API turns a photo of tools on a sheet of paper into outlines in millimetres, or a finished bin with a pocket for every tool.

Every path below is relative to the base URL. The same API also answers under /api, so /engine/v1/generate is also /api/engine/v1/generate.

Quick start

1. Make an account on VERTEX (free), and sign in.
2. Make a key in the console. It starts with vx_ and is shown once: keep it somewhere safe, like an environment variable.
3. Make your first model. This makes a 3 × 2 bin, six units tall, with three compartments:

The answer is the file itself. Its headers say which serial number it carries, which engine made it, which parts it holds, and the request id of the call.

Authentication

Send your key on every call, in the Authorization header:

Authorization: Bearer vx_YOUR_KEY

• Keep keys secret. Use them from a server, never in a web page or an app someone can unpack.
• One key per use (a shop, a bot, a script), so you can see each one's calls and revoke one without stopping the rest.
• Revoke a key in the console and it stops working at once. Its past calls stay in your log, under its name.
• Lock a key to your server's addresses and a leaked copy is useless anywhere else. See Locking a key.
• We only ever store a fingerprint of your key, plus its first few characters (like vx_ab12…) so you can tell keys apart.

Requests and responses

Send JSON with Content-Type: application/json, except a tracer photo, which can be the raw image. Successful calls answer with a file or with JSON. Every answer carries these headers:

An error is JSON with one plain sentence that says what went wrong and how to fix it:

{ "error": "gridX is at most 10." }

Kinds and settings

Straight from the engine, so this list is always current. Pick a kind:

How tracing works By invitation

Lay tools on a sheet of paper and photograph them from above. The paper is the ruler: we find its corners, straighten the photo, and measure every tool in millimetres.

Photos are traced and thrown away; jobs are kept for 15 minutes. A photo that fails costs nothing from your allowance.

Taking good photos

• Straight from above, with the whole sheet in view and a little table round it.
• A darker surface than the paper, so its edges stand out.
• Even light: daylight or two lamps. Avoid a single hard light that throws long shadows.
• Tools flat and apart, not touching each other or the edge of the sheet.
• Shiny steel: tilt the light a little to kill glare.

Errors

Retry 429 and 5xx answers with a growing wait (1 s, 2 s, 4 s…). Don't retry 4xx answers unchanged: they'll fail the same way.

Limits, plans and quotas

Your account's plan sets the engine API's limits. The day's allowance belongs to your account and is shared by all your keys: more keys never means more calls. The per-minute limit is per key, so one busy script can't use it all up. The plans and prices are on the overview, and you can change plan in the console at any time.

Every file comes back with X-Mint-Plan (your plan's id). If the call counted as extra use past the day's allowance, it also has X-Mint-Extra-Use: 1. Set a monthly limit for extra use in the console. Once it's reached, calls get a 429 saying so until the 1st.

Need more? Tell us what you're building.

Locking a key to your servers

In the console, press Lock on a key and list the addresses it may be used from: single IPs (IPv4 or IPv6), or IPv4 ranges like 203.0.113.0/24, up to 20. From anywhere else the key answers 403, even with the right key. Leave the list empty to let the key work from anywhere again.

Lock keys that run on servers with fixed addresses. Don't lock a key used from a laptop or a home connection whose address changes.

Webhooks

Add an https:// address in the console and we'll POST to it when something happens to your API account. You get a signing secret (whsec_…) once, when you add it.

Each delivery is JSON, with three headers:

{
  "id": "evt_8sKq2mZ0aB1c",
  "type": "usage.80",
  "created": 1790000000,
  "data": { "key": { "id": 12, "name": "Shop orders", "hint": "vx_ab12…" }, "used": 800, "limit": 1000, "window": "24h" }
}

Check every signature before trusting a delivery, and refuse ones more than five minutes old:

import crypto from "node:crypto";

// rawBody: the request body exactly as it arrived, before JSON.parse.
function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const got = Buffer.from(parts.v1 || ""), want = Buffer.from(expected);
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return fresh && got.length === want.length && crypto.timingSafeEqual(got, want);
}

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return abs(time.time() - int(parts["t"])) < 300 and hmac.compare_digest(expected, parts.get("v1", ""))

• Answer 2xx quickly (within 8 seconds), then do the work. Anything else counts as a failure.
• Retries: after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours, then the delivery is marked failed. Every try is listed under Deliveries in the console, with the answer we got.
• We don't follow redirects, and addresses must be public: private and local networks are refused.
• Up to five webhooks per account.

Request ids and serials

Everything you make can be traced, by you and by us:

• Every call gets a request id (X-Request-Id), errors included.
• Every file carries a serial number (X-Vertex-Serial), stamped into the file. It records when and how the file was made, and nothing about you.
• Your console lists every call your keys made: when, the endpoint, what you asked for, the result, how long it took, the serial and the request id. Search it by request id, serial or path.
• We watch for trouble around the clock: sudden spikes, keys that keep failing, key guessing and scraping. If something looks wrong with your key we may get in touch, or block an address while we look.
• Delete your VERTEX account and the account, IP address, client and settings on your calls are wiped from the log; only anonymous counts stay.
• We keep the call log for two years, to answer support questions, spot abuse and keep the service healthy. It holds the key used, the account, the IP address and the client's user agent, never the key itself.

Versions and changes

The API is versioned in its path (/v1). Within v1 we only add things: new kinds, new settings, new fields. Nothing you rely on is removed or renamed without a new version and notice.

The engine has its own version, sent with every file. When a generator's shapes change, the engine version moves on, and old files can always be matched to the engine that made them. Recent engine changes:

Licence and fair use

• Models you generate are CC BY-NC-SA 4.0: free to print and remix with credit, not for sale. To sell what you make, apply for a commercial licence.
• Generate what someone asked for, when they asked. Please don't loop the API to build a catalogue.
• Don't share keys, or use one key for many unrelated customers.
• We may slow or revoke a key that's hurting the service, and we'll tell you why.

Support

Stuck? Write to us, or ask in the Discord. Include the request id (or the file's serial), and we can see exactly what happened.

Is something down? The status page shows every part of the API, 90 days of history and any incident we are working on. Follow it by RSS, or with an incident.updated webhook.