Docs
The Mint Motive API
Three APIs on one engine. The Engine API turns settings into print-ready models, 80 kinds of them (Gridfinity bins and baseplates, Skådis, 10-inch rack panels, kitchen, desk and home organisers and more, every one listed under Kinds and settings), 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. The Print AI API checks a print before slicing, after slicing and from a photo after printing, and gives the exact settings to change. And the free Star Citizen API serves ships, missions, items and shops from Verse Atlas.
Base URL
https://api.mintmotive.com.au
Format
JSON in, files or JSON out
Engine
—
Checking…
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
- Make an account on VERTEX (free), and sign in.
- Make a key in the console. It starts with
vx_and is shown once: keep it somewhere safe, like an environment variable. - 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
| Key | For | Where it comes from |
|---|---|---|
vx_… | Engine API (or every API, on keys made before keys were split) | You make it in the console, up to five live keys per account. |
ai_… | Print AI | Made in the console. Opens Print AI only. |
sc_… | Star Citizen data | Made in the console. Reads the Star Citizen API only. |
tk_… | Tracer API | Issued by us to partners, with a monthly photo allowance and a price per photo. Test keys work before launch and are never billed. |
- 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.
- Test keys (
vx_test_…, tick "Test key" when you make one): every call is checked exactly like a real one, but files come back as a 20 mm test cube (headerX-Mint-Test: 1), photo diagnosis returns a fixed sample report, and nothing counts against your plan. They work even while an API is switched off. Two per account, 20 calls a minute. - Team keys: start a team in the console (Team), invite people by handle or email, and make keys for the team. They run on the team owner's plan and count toward the owner's keys. Owners and admins make, lock, limit and revoke them; members see them and their calls. Closing a team revokes its keys.
- 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:
| Header | What it is |
|---|---|
X-Request-Id | This call's id, like req_8KQe2f…. On every answer, errors too. Quote it when you ask for help. |
X-Vertex-Serial | The serial number stamped into the file, like VX-2610-8K2F-QP7D. On every file. |
X-Vertex-Engine | The engine version that made the file. |
X-Vertex-Parts | The parts in the file, comma separated. |
An error is JSON with one plain sentence that says what went wrong and how to fix it:
{ "error": "gridX is at most 10." }
GET /engine/v1
What the engine is right now: its version, what it can make, the formats, the limits, and whether it's switched on. No key needed.
{
"engine": "1.33.0",
"version": 1,
"enabled": false,
"kinds": ["bin", "baseplate", "holder", "labels", "skadis", "enclosure", "simrig", "tslot", "swatch", "spool", "knob", "dragchain", "hinge", "jar", "stand", "deskhook", "planter", "cutter", "keychain", "bagclip", "coaster", "cablewrap", "battery", "shelfbracket", "headphone", "keyrack", "plantmarker", "toothbrush", "spicerack", "broomholder", "bookend", "laptopstand", "monitorriser", "desktidy", "cablebox", "chargedock", "deskdrawer", "deskhanger", "controllerrack", "grommet", "leadhanger", "bikehook", "shoerack", "petbowl", "routershelf", "remotecaddy", "tabletholder", "glassesrack", "familycharger", "hairholder", "lidrack", "mughooks", "wraprack", "glassrail", "cutlerytray", "hallhooks", "toytray", "shoehorn", "bathcaddy", "spoolrack", "propagator", "gameinsert", "dicetower", "cardholder", "pillbox", "dateclip", "magnetholder", "jewellerystand", "tierack", "capsuleholder", "doorstop", "tubesqueezer", "clothespeg", "towelholder", "sinktidy"],
"formats": ["stl", "3mf", "obj"],
"limits": { "perMinute": 30, "perDay": 1000, "keys": 5 }
}
GET /engine/v1/kinds
Every kind and the default of every setting. No key needed. The settings are the same ones the generator pages use: set a model up on the site and the address bar spells out the names and values. The full list is under Kinds and settings.
POST /engine/v1/parts
A dry run. It lists the parts a model is made of, with sizes in millimetres and triangle counts, and makes no file. It's handy for checking settings, or for asking for one part as STL.
| Field | Type | What it is | |
|---|---|---|---|
kind | string | required | One of the kinds. |
params | object | Settings. Anything you leave out takes its default. |
{
"kind": "bin",
"engine": "1.33.0",
"parts": [
{ "name": "bin", "triangles": 2688, "size": [125.5, 83.5, 46.6] }
]
}
POST /engine/v1/generate
Makes the model and answers with the file.
| Field | Type | What it is | |
|---|---|---|---|
kind | string | required | bin, baseplate, holder, labels, skadis, enclosure (Pi and Arduino cases), simrig, tslot, swatch (filament swatches), spool (spool and dry-box parts), knob (knobs and drawer pulls), dragchain (cable drag chains), hinge (hinges and hinged boxes), jar (screw-top jars), stand (phone and tablet stands), deskhook (desk hooks), planter (plant pots and drip trays), keychain (name keychains and tags), bagclip (bag clips), coaster (coasters), cablewrap (cable winders and straps), battery (battery trays and Gridfinity battery bins), shelfbracket (shelf brackets), headphone (headphone stands), keyrack (key racks), plantmarker (plant markers), toothbrush (toothbrush holders), spicerack (spice racks), broomholder (broom and mop holders), bookend (bookends), laptopstand (laptop stands), monitorriser (monitor risers), desktidy (pen pots and desk tidies), cablebox (cable boxes), chargedock (charging docks), deskdrawer (under-desk drawers), deskhanger (under-desk headphone hooks), controllerrack (controller and headset racks), grommet (desk cable grommets), leadhanger (extension lead and hose hangers), bikehook (bike and helmet wall hooks), shoerack (shoe and boot wall racks), petbowl (raised pet bowl stands), routershelf (router and modem wall shelves), remotecaddy (remote control caddies), tabletholder (wall tablet holders), glassesrack (glasses wall racks), familycharger, hairholder, lidrack, mughooks, wraprack, glassrail, cutlerytray, hallhooks, toytray, shoehorn, bathcaddy, spoolrack, propagator, gameinsert, dicetower, cardholder, pillbox, dateclip, magnetholder, jewellerystand, tierack, capsuleholder (capsule: nespresso, dolcegusto, kcup, vertuo or custom), doorstop, tubesqueezer, clothespeg, towelholder (mount: wall or under), sinktidy or cutter (cookie cutters; send shape: "drawing" with drawing outlines for your own). GET /kinds lists each one’s settings and defaults. |
params | object | Settings. Anything you leave out takes its default. | |
format | string | 3mf (default, every part, keeps colours), stl (one part) or obj (every part). | |
part | string | For STL from a model with several parts: which one. /parts lists their names. | |
name | string | The file's name, without the extension. |
curl -X POST https://api.mintmotive.com.au/engine/v1/generate \
-H "Authorization: Bearer $MINT_KEY" \
-H "Content-Type: application/json" \
-d '{ "kind": "baseplate", "format": "3mf", "params": { "gridX": 6, "gridY": 4, "bed": 256 } }' \
-o baseplate.3mf -D headers.txtA baseplate bigger than your bed comes back split into tiles that fit, with the clips that join them, all in one 3MF.
Custom generators
Make your own generator out of our engine's parts, without running any code of your own. A generator is a recipe. It has inputs (numbers with a range, choices, or on/off switches) and parts. Each part is one of the kinds from GET /engine/v1/kinds, with its settings, a place (at, in mm) and a turn (rotate, in degrees about x, y and z).
- A setting can be written as is (
"gridY": 1), name an input ("gridX": "$count"), or be a formula ("heightUnits": "=3 + $tall * 3"). Formulas take numbers, inputs,+ - * /, brackets andmin max round floor ceil abs clamp. Nothing else runs. An on/off input counts as 1 or 0. whenswitches a part on or off ("when": "$withLid").repeat: { count, step: [x, y, z] }makes a row of copies.- Limits: 24 inputs, 24 parts, 48 pieces once repeated, 2 million triangles, 32 KB, and 50 generators per account.
{
"name": "Bin row",
"inputs": [
{ "id": "count", "type": "number", "min": 1, "max": 4, "default": 2 },
{ "id": "tall", "type": "bool", "default": false }
],
"parts": [
{ "kind": "baseplate", "name": "plate", "params": { "gridX": "$count", "gridY": 1 } },
{ "kind": "bin", "name": "bin", "params": { "gridX": 1, "heightUnits": "=3 + $tall * 3" },
"at": [0, 0, 5], "repeat": { "count": "$count", "step": [42, 0, 0] } }
]
}
The check, and Verified
Every save is checked on our reference engine. It runs the defaults, every number at its smallest and largest, every choice and every switch. It reports parts that are broken (refused or empty), off-spec (below the bed), and settings or parts that change nothing (not a setting of that kind, always the kind's default, the same part twice, or an input nothing uses). You get a match score. A generator scoring 95% or more, with nothing broken or off-spec, is Verified. Make and check them in your console, or with POST /engine/v1/custom/check (your key, or signed in; this never counts as a call).
Using one
POST /engine/v1/custom/:id/generate with { "inputs": { … }, "format": "3mf" } answers with the file, just like /generate, on your plan's allowance. Inputs are kept inside their ranges. X-Vertex-Verified says whether it passed the check. Your own generators work for you; once published, anyone's key can use them. GET /engine/v1/custom lists yours and the published ones, and GET /engine/v1/custom/:id gives one's inputs.
curl -X POST https://api.mintmotive.com.au/engine/v1/custom/cg_AbC123xy/generate \
-H "Authorization: Bearer $MINT_KEY" -H "Content-Type: application/json" \
-d '{ "inputs": { "count": 3, "tall": true }, "format": "3mf" }' -o bin-row.3mf
Kinds and settings
Straight from the engine, so this list is always current. Pick a kind:
Loading the engine's settings…
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.
POST /trace/v1/jobs
Send the photo. You get a job id at once.
GET /trace/v1/jobs/:id
Check every second or two until it's done (usually a few seconds).
Use the outlines, or GET …/bin for a ready bin with a pocket per tool.
Photos are traced and thrown away; jobs are kept for 15 minutes. A photo that fails costs nothing from your allowance, and is never billed.
Billing per photo. Your agreement sets a price per photo and how many photos each month are free. Only photos that traced count. Each month's total goes on your account's next invoice as one line. GET /trace/v1 shows your price and what this month owes so far. Test keys are never billed.
GET /trace/v1
Your key's name, whether it's a test key, this month's allowance and use, and (for a live key) its price and what this month owes so far, in cents.
{
"name": "VERTEX tracer API",
"version": 1,
"papers": ["a4", "letter", "a5", "a3"],
"key": {
"name": "Acme Tools", "test": false, "quota": 500, "usedThisMonth": 42,
"price": { "centsPerPhoto": 5, "freePhotos": 20, "owedThisMonthCents": 110 }
},
"limits": { "perMinute": 6, "atOnce": 2, "maxPhotoMb": 20 }
}
POST /trace/v1/jobs
Send the photo as the request body (JPEG, PNG or HEIC, up to 20 MB), or as JSON { "image": "<base64>", "paper": "a4" }. Say the paper size with ?paper=: a4 (default), letter, a5 or a3.
curl -X POST "https://api.mintmotive.com.au/trace/v1/jobs?paper=a4" \
-H "Authorization: Bearer $TRACE_KEY" \
-H "Content-Type: image/jpeg" \
--data-binary @tools.jpg{ "id": "Qm9zc2Vz8a", "status": "running", "check": "/api/trace/v1/jobs/Qm9zc2Vz8a" }
GET /trace/v1/jobs/:id
While it runs: { "status": "running", "seconds": 2 }. If it fails: { "status": "failed", "error": "…" } with what to change. When it's done:
{
"id": "Qm9zc2Vz8a",
"status": "done",
"paper": { "name": "A4", "widthMm": 210, "heightMm": 297 },
"tools": [
{
"name": "pliers",
"lengthMm": 215.6,
"widthMm": 58.2,
"areaMm2": 6120.4,
"outline": [[12.4, 30.1], [14.0, 29.6], "…"]
}
],
"bin": "/api/trace/v1/jobs/Qm9zc2Vz8a/bin"
}
Outlines are in millimetres on the straightened sheet, laid out as the tools lay on the paper. name is what the tool looks like, or just tool.
GET /trace/v1/jobs/:id/bin
A Gridfinity bin with a pocket for every tool: the smallest bin they fit in, up to 8 × 8. It carries a serial like any file.
| Query | Default | What it is |
|---|---|---|
format | stl | stl or 3mf. |
clearance | 1 | Millimetres added round each tool (0–5). |
depth | 20 | Pocket depth in millimetres (5–60). |
finger | 22 | Finger hole diameter (0 for none, up to 35). |
POST /trace/v1/pocket
One tool in, a smooth cut-out pocket out, ready for a foam insert or a tray: the tool's outline, the same outline with clearance added and rounded, and both as DXF and SVG files in real millimetres. It answers at once (a few seconds), counts as one photo, and only if it worked.
Tell it where the tool is: send one or more points on the tool, in photo pixels, one on the head and one on the handle. Everything the points touch becomes one solid tool, so a tool with a metal head and rubber grips doesn't come back in pieces. Add neg points on a neighbour that must stay out.
curl -X POST "https://api.mintmotive.com.au/trace/v1/pocket?point=812,340&point=905,1490&offset=3" \
-H "Authorization: Bearer tk_…" \
--data-binary @pliers.jpg| Query or JSON field | Default | What it is |
|---|---|---|
point=x,y (repeat) / tools | every tool found | Points on the tool. As JSON: "tools": [{ "pos": [[812, 340], [905, 1490]], "neg": [[40, 60]] }], one entry per tool (up to 8). |
offset / offsetMm | 3 | Clearance added round the tool, in millimetres (0–30), with rounded corners. |
px_per_mm / pxPerMm | from the A4 sheet | Only when there is no A4 sheet in the photo and you know the scale. |
settings | JSON only. Fine tuning: close_mm, smooth_sigma_mm, simplify_mm, join_gap_mm, round_concave_mm. |
{
"tools": [
{
"lengthMm": 214.9,
"widthMm": 62.3,
"areaMm2": 9140.2,
"tool": [[91.2, 40.1], [92.0, 39.7], "…"],
"pocket": [[88.3, 37.0], [89.6, 36.4], "…"],
"report": { "ok": true, "warnings": [], "deviationMm": 0.04, "solidity": 0.81 }
}
],
"dxf": "0\nSECTION\n…",
"svg": "<svg …>",
"offsetMm": 3
}
Coordinates are millimetres from the corner of the A4 sheet. The dxf has closed polylines on two layers, POCKET (cut this) and TOOL (the tool's own outline). The svg is drawn at true size. Always read report: if ok is false, warnings says what to retake or change, for example a tool cut off at the edge, a sheet photographed at a steep angle, or a piece of the tool left out.
A photo that can't be done comes back as 422 with what to change (no A4 sheet in view, no tool found), and doesn't count.
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.
How Print AI works New
Print AI checks a 3D print at every step and says exactly what to change. It checks the model before slicing (overhangs, bridges, bed contact, a closed mesh, the best way up), the slicer settings after slicing (temperatures, layers, cooling and retraction for your filament and nozzle), and a photo after printing (Print Doctor names the fault, boxes it on the photo and gives the settings that fix it).
A Print AI key (ai_…) or an all-products developer key (vx_…) works here, on your plan's allowance. GET /ai/v1 says what's ready; GET /ai/v1/filaments lists each filament family's safe ranges. Neither needs a key.
The VERTEX slicer plugin (OrcaSlicer, Bambu Studio and PrusaSlicer post-processing) runs the settings checks on your computer for free, and sends the settings (never your model) here when you set VERTEX_API_KEY.
POST /ai/v1/check/settings
Slicer settings against safe ranges. Send any of these:
- JSON:
{ "settings": { "filament_type": "PETG", "nozzle_temperature": 275, … }, "context": { "nozzle": 0.4 } }. Setting names are your slicer's own; OrcaSlicer, Bambu Studio and PrusaSlicer names all work. - G-code as the body (
text/plain, up to 200 MB). The settings comments the slicer writes are read; the moves are skipped. - A sliced 3MF as the body (
model/3mf).
With a file as the body, give the context on the query string: ?filament=PETG&nozzle=0.4.
curl -X POST "https://api.mintmotive.com.au/ai/v1/check/settings?filament=PETG" \
-H "Authorization: Bearer $MINT_KEY" \
-H "Content-Type: text/plain" \
--data-binary @part.gcodePOST /ai/v1/check/model
A model before slicing. Send an STL or 3MF as the body (up to 50 MB), or { "kind", "params" } to check any Engine API model. You get its size, volume, whether the mesh is closed, how much overhangs and bridges over air, how much sits on the bed, and the six flat ways it could lie, with the best one.
| Query | Default | What it is |
|---|---|---|
bed | Your printer's build volume in mm, e.g. 256,256,256, to check it fits. | |
overhangAngle | 45 | The steepest overhang (from upright) that prints without support (20–80). |
{
"findings": [
{ "code": "better-orientation", "severity": "info", "confidence": 0.75,
"message": "Laid upside down, it needs about 0 mm² of support instead of 3500 mm² and sits on 3600 mm² of bed.",
"fixes": [{ "id": "orient:-z", "setting": "orientation", "from": "+z", "to": "-z" }] }
],
"stats": { "sizeMm": [60, 60, 35], "volumeCm3": 21, "closed": true, "overhangMm2": 0, "bridgeMm2": 3500, "bedContactMm2": 100 },
"orientation": { "current": "+z", "best": "-z", "options": [ … ] },
"model": "model-0.1.0", "summary": "2 tips."
}
POST /ai/v1/diagnose/photo
Print Doctor. Send a photo of a finished or failed print as the body (JPEG, PNG, WebP or HEIC, up to 12 MB), or { "image": base64, "context": { … }, "settings": { … }, "share": false }. Each finding names the fault (spaghetti, warping, stringing, under-extrusion, layer shift, poor first layer, elephant's foot, ringing and more), boxes it on the photo as fractions of the image ([x, y, w, h]), and gives the settings to change. Tell it the filament and printer for sharper answers. Photos are looked at and thrown away, unless you send share: true to help Print Doctor learn. 6 photos a minute and 200 a day per key.
POST /ai/v1/outcomes
Tell us how the print went, so the checks learn which fixes work: { "job": "your-id", "result": "good" | "failed" | "fixed", "finding": "warping", "fixedBy": "bed_temperature:105", "note": "…" }. Answers 202.
POST /ai/v1/watch/frame?job=…: live failure watch
Send a frame from the printer's camera every 20 seconds or so while it prints (the body is the JPEG or PNG; job is your own id for the print, the same on every frame). You get back action: continue, check (something's worth a look) or pause. It only says pause when two frames in a row show a print-ending fault: spaghetti, a layer shift, a clog or layers splitting. One blurry frame never stops a print. You also get message, fault, streak and the same findings as a photo diagnosis. One frame every 20 seconds per job; frames count toward the photo allowance.
curl -X POST "https://api.mintmotive.com.au/ai/v1/watch/frame?job=benchy-42" \
-H "Authorization: Bearer $MINT_KEY" -H "Content-Type: image/jpeg" \
--data-binary @frame.jpg
# → { "action": "check", "message": "Keep an eye on it: …", "fault": "spaghetti", "streak": 1, … }
POST /ai/v1/apply
Write fixes into your settings file. Send the file as the body: a PrusaSlicer .ini, a Bambu Studio or OrcaSlicer .json preset, or a .3mf project. Add ?name= (its file name, so we know the format) and ?fixes=, a JSON list of { "setting", "to" } straight from a check's findings. You get the same file back with the fixes written in, in each slicer's own setting names. The X-Fixes-Applied header lists what changed, and X-Fixes-Missing lists what isn't in the file. GET /ai/v1 lists the settings that can be fixed under fixable. G-code is already sliced: fix the profile and slice again.
curl -X POST "https://api.mintmotive.com.au/ai/v1/apply?name=profile.ini&fixes=%5B%7B%22setting%22%3A%22nozzle_temperature%22%2C%22to%22%3A215%7D%5D" \ -H "Authorization: Bearer $MINT_KEY" --data-binary @profile.ini -o profile-fixed.ini
GET /ai/v1/recipes and POST /ai/v1/recipes/:id/apply: your VERTEX Recipes
GET /ai/v1/recipes lists your own Recipes on VERTEX (id, title, fileName, verified). POST /ai/v1/recipes/:id/apply works like /apply, and the fixed file then replaces that Recipe's profile. It only reaches the Recipes of the account that owns the key. The new file goes through the usual safety checks, and a verified Recipe is checked again before it shows as verified. If none of the fixes are in the file, the Recipe is left as it was (400). Test keys can't change Recipes. Profiles can be up to 20 MB.
{ "applied": ["nozzle_temperature"], "missing": [], "recipe": { "id": "k3Jd9sQe", "title": "PETG on the P1S", "url": "/recipes/k3Jd9sQe", "fileName": "profile-fixed.ini" }, "held": false }
Findings and fixes
Every check answers { findings, model, summary }. model names the checker version (e.g. settings-0.2.0), so you can tell when the rules changed.
| Field | What it is |
|---|---|
code | What was found, e.g. temp-high-for-filament, layer-too-tall, steep-overhangs, warping. Stable: build on it. |
severity | fail (it won't print), warn (it may fail) or info (a tip). |
message | Plain words, ready to show your users. |
confidence | 0 to 1. |
fixes | Each { id, setting, from, to, unit, why }: the slicer setting, its value now and what to set it to. Send the id back as fixedBy on an outcome. Once three or more makers have reported back on a fix for that fault, it also has trackRecord: { worked, tried }, and the fixes that worked most reliably come first. |
test | A quick test print that confirms the cause. |
box | Photos only: where the fault is. |
How the Star Citizen API works Free
Everything on Verse Atlas, from your own code: ships with prices and where to buy them, every mission with pay and reputation, items, shops and places. Free for fan sites, chat bots, overlays and tools.
- Key: a Star Citizen data key (
sc_…) from the console, sent asAuthorization: Bearer sc_…. It reads this API and nothing else, which makes it the right key for a bot. An older all-productsvx_…key works too. - Price: free. 30 calls a minute per key and 1,000 a day per account (the free plan's limits), on every plan. Star Citizen calls are never billed as extra use, and they don't use up your engine allowance.
- Answers: lists answer
{ "data": [...], "next", "total" }; single things answer{ "data": {...} }. Passnextback ascursorfor the next page;limitis up to 100. Every answer has asourceblock with attribution. - Caching: every answer has an
ETag. Send it back asIf-None-Matchand unchanged data comes back as a304, which is free. Rate-limit headers (X-RateLimit-Limit,-Remaining,-Reset,-Day-Limit,-Day-Remaining) come with every answer. - Freshness: prices refresh every few hours; game data after every patch.
GET /sc/v1says which game version and build you're getting.
{
"data": { "id": "drak-cutlass-black", "name": "Cutlass Black", "maker": "Drake Interplanetary", "cargo": 46,
"crew": { "min": 3, "max": 3 }, "pledge": { "usd": 110, "available": true },
"buy": [{ "auec": 2010960, "terminal": "New Deal - Teasa Spaceport - Lorville", "place": "Lorville", "system": "Stanton", "updated": "2026-10-02" }],
"url": "https://verse.mintmotive.com.au/ships/drak-cutlass-black" },
"source": { "provider": "Verse Atlas", "url": "https://verse.mintmotive.com.au",
"data": ["Star Citizen Wiki", "UEX Corp", "FleetYards", "RSI"], "gameVersion": "4.10.2",
"notice": "Unofficial. Star Citizen® is a trademark of Cloud Imperium Rights LLC." }
}
Credit, please. Show "Data: Verse Atlas" with a link wherever you display it, plus the sources in the source block. Some of the data (from the Star Citizen Wiki) is CC BY-SA 4.0, which needs credit and the same licence for what you build from it. Follow CIG's fan content rules: no selling Star Citizen data or passing your project off as official. Unofficial. Star Citizen® is a trademark of Cloud Imperium Rights LLC.
GET /sc/v1/ships
Every ship and vehicle.
| Query | What it does |
|---|---|
q | Words in the name, maker or role. |
maker | A maker's name or code, e.g. drake, RSI. |
role | e.g. cargo, mining, fighter. |
size | A size name (small, medium, large, capital) or class (1–6). |
buyable=1 | Only ships sold in game for aUEC. |
flyable=1 | Only ships you can fly now. |
sort | name, price (cheapest in game), pledge, cargo, size, length, crew or speed. Put - in front for high to low. |
GET /sc/v1/ships/:id
One ship with everything: specs, in-game and rental prices, pledge price and store packages, images, top and side renders, a 3D model, in-game screenshots and variants. Add include=gallery,paints for the store gallery and every paint.
GET /sc/v1/ships/:id/where-to-buy
Every shop that sells or rents it, with prices and locations, and the pledge price.
curl "https://api.mintmotive.com.au/sc/v1/ships/drak-cutlass-black?include=paints" \
-H "Authorization: Bearer $MINT_KEY"GET /sc/v1/missions
Every contract: giver, faction, pay, reputation gained and lost, rank needed, systems, locations and legality.
| Query | What it does |
|---|---|
faction | A faction's id or slug, e.g. bit-zeros. |
giver | Who hands out the contract. |
type | e.g. Mercenary, Delivery, Assassination. |
system | Stanton, Pyro or Nyx. |
legal | 1 lawful only, 0 unlawful only. |
minPay | At least this many aUEC. |
maxRank | Only contracts you can take at this reputation. |
GET /sc/v1/missions/:id
One contract: pay, reputation gained and lost, rank needed, locations and the briefing.
GET /sc/v1/factions and GET /sc/v1/factions/:id
Every mission giver and faction, and one faction with its full rank ladder (the reputation each rank needs).
GET /sc/v1/reputation/plan?faction=&from=&to=
The contracts that climb fastest between two ranks. from and to are rank names or reputation numbers; from starts at Neutral and to at the top rank. You get each step up the ladder with the best contracts for it (most reputation first) and how many runs each takes, plus the total.
{ "data": { "faction": { "slug": "headhunters", "name": "Headhunters" }, "from": 0, "to": 2200, "runs": 23,
"steps": [{ "from": { "name": "Neutral", "rep": 0 }, "to": { "name": "Freelancer", "rep": 800 }, "need": 800, "runs": 8,
"missions": [{ "id": "…", "title": "…", "gain": 100, "runs": 8, "pay": { "min": 25000, "max": 25000, "currency": "aUEC" } }] }, … ] } }
GET /sc/v1/items
Weapons, armour, components and consumables, with their stats. Filters: q, type, size, maker. GET /sc/v1/items/:id is one item.
GET /sc/v1/items/:id/where-to-buy
Every shop that sells the item, cheapest first, with the shop's place and system.
GET /sc/v1/locations
Landing zones, stations and outposts, with their services (fuel, repair, clinic, refinery and more). Filters: q, system, kind. GET /sc/v1/locations/:id lists its terminals.
GET /sc/v1/terminals/:id
One shop terminal and what it sells: ships, rentals and items, with prices.
GET /sc/v1
Game version, data build time, counts and whether the API is switched on. No key needed. GET /sc/v1/version answers the same with a key.
GET /sc/v1/search?q=
One search across ships, items, missions, places and factions: the top ten of each.
Errors follow the rest of the API: 400 names the filter it won't take, 401 no key or a wrong key, 403 the key is locked to other addresses or is for another product, 404 no ship, mission or item with that id, 429 over a limit, 503 switched off or the data is still loading.
A fleet viewer in 20 lines
A page that shows your org's ships with their renders, cargo and crew, and the cheapest place to buy each in game. Run it on your server (keys stay secret), and send the page the result.
// fleet.mjs: node fleet.mjs drak-cutlass-black misc-prospector anvl-carrack
const KEY = process.env.MINT_KEY, BASE = 'https://api.mintmotive.com.au/sc/v1';
const get = async (path) => {
const res = await fetch(BASE + path, { headers: { Authorization: `Bearer ${KEY}` } });
if (!res.ok) throw new Error((await res.json()).error);
return (await res.json()).data;
};
const fleet = await Promise.all(process.argv.slice(2).map((id) => get(`/ships/${id}`)));
const rows = fleet.map((s) => {
const shop = [...s.buy].sort((a, b) => a.auec - b.auec)[0];
return `<figure><img src="${s.images.side || s.image}" alt="">
<figcaption><b>${s.fullName}</b> · ${s.cargo ?? 0} SCU · crew ${s.crew.min}–${s.crew.max}
· ${shop ? `${shop.auec.toLocaleString()} aUEC at ${shop.terminal}` : `$${s.pledge.usd ?? '?'} pledge`}</figcaption></figure>`;
});
const credit = '<p>Data: <a href="https://verse.mintmotive.com.au">Verse Atlas</a>. Unofficial. Star Citizen® is a trademark of Cloud Imperium Rights LLC.</p>';
await import('node:fs').then((fs) => fs.writeFileSync('fleet.html', `<h1>Our fleet</h1>${rows.join('')}${credit}`));
console.log(`fleet.html: ${fleet.length} ships, ${fleet.reduce((n, s) => n + (s.cargo || 0), 0)} SCU of cargo`);The same in Python, for a chat bot's "price" command:
import os, json, urllib.request
def sc(path):
req = urllib.request.Request("https://api.mintmotive.com.au/sc/v1" + path,
headers={"Authorization": f"Bearer {os.environ['MINT_KEY']}"})
return json.load(urllib.request.urlopen(req))["data"]
where = sc("/ships/drak-cutlass-black/where-to-buy")
best = min(where["buy"], key=lambda b: b["auec"])
print(f"Cutlass Black: {best['auec']:,} aUEC at {best['terminal']} ({best['system']})")More on Verse Atlas for developers.
Errors
| Status | Means | What to do |
|---|---|---|
| 400 | A setting the generator won't take. The message names it. | Fix that setting. /kinds shows the defaults. |
| 401 | No key, a mistyped key, or a revoked key. | Check the header and the key in the console. |
| 403 | The key is locked to other addresses, a tracer key was revoked, or calls from your address are blocked. | Call from an allowed address, or update the key's lock. Write to us if you think a block is wrong. |
| 404 | No such job (jobs last 15 minutes), or a wrong path. | Start a new job. |
| 409 | The job hasn't finished tracing. | Wait, then ask for the bin again. |
| 413 | Too many settings, or a photo over 20 MB. | Send less, or a smaller photo. |
| 423 | That generator is paused for maintenance. | Try again later. |
| 429 | Over a limit (per minute, per day, at once, or the month's photos). | Wait and retry, slowing down. The message says which limit. |
| 503 | The API isn't switched on yet. | Watch the status on the overview page. |
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.
Each key's own limits. In the console, give any key its own cap on calls a day and on extra use a month (in dollars, past your plan's daily allowance). A key at its cap gets a 429 that says which cap it hit; your other keys carry on. They sit on top of your account's limits, never above them.
| Engine API | Tracer API | |
|---|---|---|
| Per minute | Per key, by plan (30 on the free plan) | 6 photos per key |
| Per day | Per account, shared by all its keys, by plan (1,000 on the free plan) | — |
| Past the day's allowance | Free plan: 429 until tomorrow. Paid plans: keeps working, priced per 1,000 calls and billed daily, up to your monthly limit | — |
| At once | — | 2 photos per key |
| Per month | — | Your allowance (500 to start). Photos past your free ones are billed at your price, once a month |
| Keys | By plan (5 on the free plan) | Issued by us |
| Sizes | The same limits as the site's generators (grid size, height, parts). | |
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.
| Event | Sent when |
|---|---|
usage.80 | Your account has used 80% of its calls for the day. Once a day. |
usage.limit | Your account hit its daily limit and calls are getting 429s. Once a day. |
key.created | A key was made on your account. |
key.revoked | A key was revoked, by you or by us (with our reason). |
incident.updated | An incident on the status page was opened, updated or resolved. |
webhook.test | You pressed Send a test. |
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" }
}
| Header | Holds |
|---|---|
Mint-Signature | t=<unix seconds>,v1=<hex HMAC-SHA256> of <t>.<raw body>, keyed with your secret. |
Mint-Event | The event type. |
Mint-Delivery | The event id. The same id comes again on a retry, so you can skip repeats. |
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.
SDKs: JavaScript and Python
Two small clients with no dependencies. They cover the Engine, Tracer and Print AI APIs, and turn errors into exceptions that carry the status, the message and the request id.
- JavaScript (Node 18+, Deno, Bun, browsers):
/sdk/mintmotive.mjs - Python (3.8+, standard library only):
/sdk/mintmotive.py
import { MintMotive } from 'https://api.mintmotive.com.au/sdk/mintmotive.mjs';
const mm = new MintMotive({ key: process.env.MINT_KEY });
const bin = await mm.engine.generate({ kind: 'bin', format: 'stl', params: { gridX: 2, gridY: 1 } });
const report = await mm.ai.checkSettings(gcodeText, { filament: 'PETG' });from mintmotive import MintMotive
mm = MintMotive(key=os.environ["MINT_KEY"])
f = mm.engine_generate({"kind": "bin", "format": "stl", "params": {"gridX": 2, "gridY": 1}})
open(f["name"], "wb").write(f["bytes"])
job = mm.trace_photo(open("tools.jpg", "rb").read(), paper="a4")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:
Loading…
What's new on the API
Every new feature and fix, newest first, updated almost every day. See every update, follow it in a feed reader or a chat channel (/changelog.rss), or read it as JSON from GET /api/changelog?limit=20.
Loading…
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. 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.