REST API quickstart

The REST API lets a script do what you do in the editor: read Things, change them, build them on our servers and export files. Everything is under /api/v1, documented by an OpenAPI 3.1 file at /api/v1/openapi.json (import it into Postman, Insomnia or a code generator). The developer page is at /developers.

You need an API key.

1. Who am I?

curl https://app.solidvibes.ai/api/v1/me \
  -H "Authorization: Bearer $SOLIDVIBES_API_KEY"

You get the key's workspace, its scopes and its rate limit.

2. Find a Thing and read its doc

curl "https://app.solidvibes.ai/api/v1/things?q=router" -H "Authorization: Bearer $SOLIDVIBES_API_KEY"
curl https://app.solidvibes.ai/api/v1/things/THING_ID/doc -H "Authorization: Bearer $SOLIDVIBES_API_KEY"

The doc is the whole Thing: its pieces (each with its parametric recipe), connections and Thing parameters, plus docVersion.

3. Change it with ops

Changes are Thing ops, the same edits the editor and the agent make. Send the version you read as expectedVersion:

curl -X PATCH https://app.solidvibes.ai/api/v1/things/THING_ID/doc \
  -H "Authorization: Bearer $SOLIDVIBES_API_KEY" -H "Content-Type: application/json" \
  -d '{ "expectedVersion": 12,
        "ops": [{ "op": "piece_recipe", "pieceId": "p1",
                  "ops": [{ "op": "set_parameter", "name": "width", "value": 80 }] }],
        "message": "Wider for the new router" }'

• 200 returns the new docVersion and a plain description of what changed.
• 409 version_conflict means someone saved first. Read the doc again and re-apply your ops.
• Useful ops: set_thing_parameter, piece_recipe (with recipe ops such as set_parameter, add_step, update_step, suppress_step), update_piece, add_connection.

Anyone with the Thing open sees the change live, and it's recorded in the history.

4. Build, mass properties and export

curl -X POST https://app.solidvibes.ai/api/v1/things/THING_ID/build -H "Authorization: Bearer $SOLIDVIBES_API_KEY" -H "Content-Type: application/json" -d '{}'
curl -X POST https://app.solidvibes.ai/api/v1/things/THING_ID/exports -H "Authorization: Bearer $SOLIDVIBES_API_KEY" -H "Content-Type: application/json" -d '{ "format": "stl" }'

A build returns, per piece, failing steps with plain-language errors, the bounding box, volume, area, mass (in the piece's material) and centre of mass. An export returns a download link valid for 10 minutes; your plan decides which formats you can export.

5. Run the agent (optional)

POST /things/THING_ID/agent with { "prompt": "add 4 mounting holes", "mode": "fast" } runs the same agent as the editor and charges the same AI credits. The proposal waits in the editor for someone to accept it, or pass "apply": true (needs things:write) to accept it right away.

The TypeScript SDK

The typed client (packages/sdk) wraps all of this, follows pagination, retries rate limits and re-reads the doc on version conflicts:

import { SolidVibes } from "@sv/sdk";

const sv = new SolidVibes({ apiKey: process.env.SOLIDVIBES_API_KEY! });
const [mount] = await sv.things.all({ q: "router mount" });
await sv.things.setParameter(mount.id, "width", 80);
const { total } = await sv.things.build(mount.id);
const stl = await sv.exports.create(mount.id, { format: "stl" });
console.log(`${total.massG} g`, stl.url);

Webhooks

To hear back when something changes through the API, add a webhook in Workspace → Developer. Each delivery has an X-SolidVibes-Signature: t=<unix time>,v1=<hex> header: compute the HMAC-SHA256 of "<t>.<raw body>" with your webhook's secret and compare, and reject timestamps older than five minutes.

Errors

Errors are JSON: { "error": { "code": "…", "message": "…" } }. Common codes: unauthorized (401), insufficient_scope and plan_required (403), not_found (404), version_conflict (409), rate_limited (429), no_credits (402).