Bitbybit CAD Cloud API

The Bitbybit CAD Cloud API lets you generate parametric 3D CAD models, convert STEP files to glTF, and run CAD kernel operations - all via HTTP from any backend, in any programming language.

Every request runs asynchronously on managed compute infrastructure. You submit a job, get a task ID, poll for completion, and download the result in the format you need (STEP, glTF/GLB, Decomposed Mesh, and more).

Quick links

Resource	Link
Interactive API reference	API Reference
TypeScript SDK	`@bitbybit-dev/cad-cloud-sdk`
Base URL	`https://api.bitbybit.dev`

What you can do

Generate parametric models - submit parameters for registered models (e.g. Dragon Cup, Phone Nest) and get downloadable 3D files
Convert STEP → glTF - upload a STEP/STP file and convert it with simple or advanced options (mesh precision, face merging, coordinate adjustment, texture embedding, and more)
Run CAD pipelines - chain operations (primitives, booleans, transforms, fillets) in a single request where steps can reference each other's outputs
Execute single CAD operations - run any supported operation by its fully-qualified identifier (e.g. occt.shapes.solid.createSphere)
Manage tasks - poll status, cancel, retry, list, and download results in multiple formats
Upload files - upload STEP files for conversion via pre-signed URLs

Authentication

All endpoints (except /health) require an API key passed as the x-api-key header:

curl https://api.bitbybit.dev/api/v1/models \
  -H "x-api-key: YOUR_API_KEY"

Keys are scoped - each key carries permissions for specific endpoint groups (models, cad, convert, files, tasks).

Async task model

Every operation that creates or transforms geometry is asynchronous:

Submit - POST your request → receive 202 Accepted with a taskId
Poll - GET /api/v1/tasks/{taskId} until status is completed (or failed)
Download - GET /api/v1/tasks/{taskId}/result/{format} → pre-signed download URL

The SDK handles polling automatically via models.run(), cad.executeAndPoll(), etc.

Output formats

Format	Extension	Description
`gltf`	`.glb`	Web-ready 3D mesh (glTF 2.0 binary)
`step`	`.stp`	Native CAD exchange format
`stpz`	`.stpz`	Compressed STEP (gzip)
`decomposed-mesh`	`.json`	Structured mesh data with face/edge decomposition

Available models

Model	Description
`dragon-cup`	Parametric dragon-scale cup with configurable height, radius, thickness, cell pattern
`phone-nest`	Parametric phone stand/nest with optional ornamental perforations

All model parameters are optional - default values produce a valid model. See the interactive API reference for full parameter documentation.

Key components

API server

The REST API at https://api.bitbybit.dev. All endpoints require an API key passed via the x-api-key header. See the full API Reference for endpoint details, request/response schemas, and examples.

Studio

Bitbybit Studio is a browser-based dashboard where you can use all of the API's features through a visual interface - generate models, convert files, build pipelines, inspect tasks, and preview 3D results. Everything you do in Studio maps directly to an API call, so it's a great way to experiment before writing code. Read more in the Studio introduction.

TypeScript SDK

The @bitbybit-dev/cad-cloud-sdk npm package provides a type-safe client for Node.js and edge runtimes. It handles request construction, error mapping, and includes a built-in polling helper.

npm install @bitbybit-dev/cad-cloud-sdk

Getting an API key

Create an account at bitbybit.dev/auth/sign-up
Subscribe to an API key plan in Studio - plans include a compute-minute allowance for running CAD operations
Create a scoped API key from your Studio dashboard - keys are scoped to specific capabilities (models, tasks, cad, convert, files)

Calling the API from any language

The API is a standard REST API, which means you can call it from any language that supports HTTP requests. Here's a minimal example using curl:

# Generate a Dragon Cup model
curl -X POST https://api.bitbybit.dev/api/v1/models/dragon-cup \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "params": { "height": 10, "radiusBottom": 5 },
    "outputs": { "formats": ["gltf"] }
  }'

# Response: { "ok": true, "data": { "taskId": "...", "status": "queued", "statusUrl": "..." } }

# Poll the task
curl https://api.bitbybit.dev/api/v1/tasks/TASK_ID \
  -H "x-api-key: YOUR_API_KEY"

# Download result when completed
curl https://api.bitbybit.dev/api/v1/tasks/TASK_ID/result/glb \
  -H "x-api-key: YOUR_API_KEY"

Using the TypeScript SDK

Initialize the client

import { BitbybitClient } from "@bitbybit-dev/cad-cloud-sdk";

const client = new BitbybitClient({
    apiKey: process.env.BITBYBIT_API_KEY,
    baseUrl: "https://api.bitbybit.dev",
});

Generate a parametric model

The models.run() method submits a model generation request, polls for completion, and returns the download URL in a single call:

const { taskId, downloadUrl } = await client.models.run("dragon-cup", {
    params: {
        height: 8,
        radiusBottom: 4,
        radiusTopOffset: 2,
        thickness: 0.6,
        scale: 1,
    },
    outputs: {
        formats: ["gltf"],
    },
});

console.log("Download:", downloadUrl);

Run a CAD pipeline

Chain multiple CAD operations - each step can reference previous steps' outputs using $ref:N:

const created = await client.cad.pipeline({
    steps: [
        {
            operation: "occt.shapes.solid.createSphere",
            params: { radius: 5, center: [0, 0, 0] },
        },
        {
            operation: "occt.shapes.solid.createBox",
            params: { width: 6, length: 6, height: 6, center: [3, 0, 0] },
        },
        {
            operation: "occt.booleans.difference",
            params: {
                shape: "$ref:0",
                shapes: ["$ref:1"],
                keepEdges: false,
            },
        },
    ],
});

// Poll until completion
const task = await client.tasks.poll(created.taskId, {
    onProgress: (t) => console.log(`Status: ${t.status}`),
});

// Download the result
const result = await client.tasks.getResult(task.taskId);
console.log("Download:", result.downloadUrl);

Execute a single CAD operation

const created = await client.cad.execute({
    operation: "occt.shapes.solid.createSphere",
    params: { radius: 3, center: [0, 0, 0] },
});

const task = await client.tasks.poll(created.taskId);
const result = await client.tasks.getResult(task.taskId);
console.log("Download:", result.downloadUrl);

Use in an Express server

import express from "express";
import { BitbybitClient } from "@bitbybit-dev/cad-cloud-sdk";

const app = express();
app.use(express.json());

const client = new BitbybitClient({
    apiKey: process.env.BITBYBIT_API_KEY,
    baseUrl: "https://api.bitbybit.dev",
});

app.post("/api/generate", async (_req, res) => {
    try {
        const result = await client.models.run("dragon-cup", {
            params: { height: 8, radiusBottom: 4 },
            outputs: { formats: ["gltf"] },
        });
        res.json(result);
    } catch (e) {
        const message = e instanceof Error ? e.message : "Unknown error";
        res.status(500).json({ error: message });
    }
});

app.get("/api/task/:id", async (req, res) => {
    try {
        const task = await client.tasks.get(req.params.id);

        if (task.status !== "completed") {
            return res.json({ status: task.status });
        }

        const result = await client.tasks.getResult(task.taskId, "glb");
        res.json({ status: "completed", downloadUrl: result.downloadUrl });
    } catch (e) {
        const message = e instanceof Error ? e.message : "Unknown error";
        res.status(500).json({ error: message });
    }
});

app.listen(3000);

Endpoints overview

Models

GET /api/v1/models - list available models
GET /api/v1/models/{name}/params - get parameter definitions
POST /api/v1/models/definitions - batch-fetch model definitions
POST /api/v1/models/{name} - generate a model (async)
POST /api/v1/models/{name}/batch - generate multiple variations (async)

CAD operations

POST /api/v1/cad/execute - run a single CAD operation (async)
POST /api/v1/cad/pipeline - run a chained pipeline (async)
POST /api/v1/cad/compound - run parallel operations (async)

Conversion

POST /api/v1/convert/step-to-gltf - simple STEP → glTF (async)
POST /api/v1/convert/step-to-gltf-advanced - full-control conversion (async)

Files

POST /api/v1/files/upload - get a pre-signed upload URL
POST /api/v1/files/{id}/confirm - confirm upload
GET /api/v1/files - list files
GET /api/v1/files/{id} - get file details
DELETE /api/v1/files/{id} - delete a file

Tasks

GET /api/v1/tasks - list tasks
GET /api/v1/tasks/{id} - get task status
GET /api/v1/tasks/{id}/result - download default result
GET /api/v1/tasks/{id}/result/{format} - download specific format
DELETE /api/v1/tasks/{id} - cancel a task
POST /api/v1/tasks/{id}/retry - retry a failed task

For full request/response schemas, see the interactive API reference.

Code examples

Full working examples are available in the open-source GitHub repo:

Node.js + SDK - Express server using @bitbybit-dev/cad-cloud-sdk
Node.js + REST - Express server using raw fetch calls
Hono + SDK - Cloudflare Workers using the SDK
Hono + REST - Cloudflare Workers using raw fetch calls

Each example includes a complete server with API routes and a browser frontend for testing.

You can also scaffold any of these example architectures instantly using our CLI tool:

npx @bitbybit-dev/create-app my-cloud-project

Select the cloud app type when prompted, then choose your preferred backend template (Hono + SDK, Hono + REST, Node.js + SDK, Node.js + REST, or .NET + REST). The CLI generates a ready-to-run project with a React + Three.js frontend, your chosen backend, and all configuration in place - just add your API key and start developing.

Next steps

Studio introduction - explore the visual dashboard
API Reference - full endpoint documentation with schemas and examples
TypeScript SDK on npm - package details and changelog

Quick links​

What you can do​

Authentication​

Async task model​

Output formats​

Available models​

Key components​

API server​

Studio​

TypeScript SDK​

Getting an API key​

Calling the API from any language​

Using the TypeScript SDK​

Initialize the client​

Generate a parametric model​

Run a CAD pipeline​

Execute a single CAD operation​

Use in an Express server​

Endpoints overview​

Models​

CAD operations​

Conversion​

Files​

Tasks​

Code examples​

Next steps​