HTTP API

This service builds a VXL document into delivery files: STEP, STL, 3MF, renders and a verification report. It runs on Vextor's Linux build cell. You need no local Vextor install: write a *.vxl.json document (for example with the vextor-vxl agent skill), send it, and download the result.

• Base URL: https://api.vx.fibonax.org
• Every route starts with /api/v1/.
• Requests and responses are JSON, except the archive download and asset uploads.

1. Quick start with the client

vextonline.py (in tools/client/ here, also bundled with the vextor-vxl skill) needs only Python 3.9+.

export VEXTONLINE_TOKEN='vxk1.<key_id>.<secret>'   # or save it in ~/.config/vextonline/token (chmod 600)

python3 vextonline.py check part.vxl.json                      # static check, about 1 s
python3 vextonline.py build part.vxl.json --output-dir out     # build, wait, download, extract
python3 vextonline.py build part.vxl.json --output-dir out \
    --asset stock=stock.step --overrides '{"width": 40}'       # with an input asset and overrides

out/ has the same layout as a local vextor vxl build:

out/generations/<name>/terminals/<part>__body.{step,stl,3mf}
out/generations/<name>/renders/*.png
out/generations/<name>/manifest-v1.json
out/report/summary.json            always for RELEASE and HOLD
out/report/revision-packet.json    for HOLD and FAILED: what to fix

Client exit codes:

2. Results: RELEASE, HOLD, FAILED

A finished build has status: "completed" and a verdict:

The build cell is development_unqualified. RELEASE means "matches the document's own measured requirements on this cell". It is not a print or engineering certification. Slicing and printing (for example in Bambu Studio) are up to you.

status: "failed" means the service could not run the build, not that the design is wrong. error.code is one of:

3. Authentication

Send your key on every request:

Authorization: Bearer vxk1.<key_id>.<secret>

• Keys are issued by the operator, and the full key is shown only once. Keep it secret.
• A missing, wrong or revoked key gets 401 unauthorized.
• Each key belongs to one tenant; you see only your own builds and uploads.

4. Endpoints

GET /api/v1/health

Returns 200 {"ok": true}. No authentication.

POST /api/v1/checks

{"document": { ...VXL... }, "overrides": {"param": 1}}

Returns 200 {"ok": true|false, "report": {...}}.

• ok: false means the document has errors. report.message names the first error code, its JSON pointer and the valid values.
• This is the same static check as vextor vxl check. It does not build.

POST /api/v1/uploads

Use this for asset files that the document declares in assets[]: STEP up to 8 MiB, STL up to 64 MiB.

{"id": "stock", "media_type": "model/step", "byte_length": 15385}

Returns 200 {"upload_key", "put_url", "put_headers", "expires_at"}.

• PUT the exact file bytes to put_url, with put_headers, within 15 minutes.
• Pass upload_key to the build.
• Uploads are deleted after 1 day.

POST /api/v1/builds

{
  "document": { ...VXL... },
  "overrides": {"width": 40},
  "timeout_ms": 240000,
  "assets": {"stock": {"upload_key": "uploads/<tenant>/<uuid>"}}
}

• Optional header Idempotency-Key: <1–128 printable ASCII>. Retrying with the same key and body returns the same build; the same key with a different body gets 409 conflict.
• Returns 202 {"build_id", "status": "queued", "status_url"}.

GET /api/v1/builds/{build_id}

Poll every 2–5 s until status is completed or failed.

{
  "build_id": "…", "status": "completed", "verdict": "RELEASE",
  "created_at": "…", "updated_at": "…", "wall_ms": 5967,
  "summary": { ... }, "revision_packet": { ... },
  "archive_url": "https://…", "expires_at": "…"
}

archive_url is a ZIP of generations/ and report/. The link is valid for 24 hours, and every poll returns a fresh one. Results are kept for 30 days.

GET /api/v1/builds?limit=20&cursor=…

Lists your builds, newest first, without summaries. If the reply has next_cursor, pass it as cursor to get the next page.

5. Limits and quotas

Typical time from submit to done:

• simple exact parts: 5–10 s;
• organic and mesh parts: 15–25 s;
• the first build after an idle period: add about 10 s.

6. Errors

All errors have the form {"error": {"code", "message", "detail?"}}.

7. Raw HTTP example

H="Authorization: Bearer $VEXTONLINE_TOKEN"
DOC=$(cat part.vxl.json)
curl -s -H "$H" -H 'content-type: application/json' \
     -d "{\"document\": $DOC}" https://api.vx.fibonax.org/api/v1/checks
ID=$(curl -s -H "$H" -H 'content-type: application/json' -H "Idempotency-Key: part-1" \
     -d "{\"document\": $DOC}" https://api.vx.fibonax.org/api/v1/builds | python3 -c 'import json,sys; print(json.load(sys.stdin)["build_id"])')
curl -s -H "$H" https://api.vx.fibonax.org/api/v1/builds/$ID      # repeat until completed

8. Not yet available

The following are not available yet:

• named variants (--variant of the local CLI); send the equivalent overrides instead;
• revisioned editing sessions;
• an MCP endpoint;
• self-service sign-up and key management (keys come from the operator).