@bitbybit-dev/cad-cloud-sdk

Type-safe TypeScript SDK for the Bitbybit CAD Cloud API. Generate parametric 3D models, run CAD operations, convert STEP files, and manage async tasks - all with full intellisense.

Server-side only. Never expose your API key in frontend code.

Scaffold a full project

The fastest way to get started is with our CLI - it scaffolds a complete backend + React frontend with this SDK pre-configured:

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

Choose from 5 backend templates: Hono + SDK, Hono + REST, Node.js + SDK, Node.js + REST, or .NET + REST. Each includes ready-to-run examples with model generation, batch operations, and CAD pipelines.

Install

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

Quick start

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

const client = new BitbybitClient({
    apiKey: process.env.BITBYBIT_API_KEY!,
});

// Generate a dragon cup - polls automatically, returns all download URLs
const { downloads } = await client.models.run("dragon-cup", {
    params: { height: 10, radiusBottom: 5 },
    outputs: { formats: ["gltf"] },
});

// downloads: [{ format: "glb", downloadUrl, filename }, { format: "metadata", ... }]
const glb = downloads.find(d => d.format === "glb");
console.log("GLB download:", glb?.downloadUrl);

What's included

| Endpoint | What it does | |----------|-------------| | client.models | Generate parametric 3D models (single + batch) | | client.cad | Execute operations, pipelines, and compound tasks | | client.convert | STEP → glTF conversion (simple + advanced) | | client.tasks | Poll, list, cancel, retry, and download results | | client.files | Upload and manage files for conversion |

All high-level methods (models.run, cad.executeAndPoll, convert.stepToGltfAndPoll) handle polling automatically and return all download URLs (including metadata) in a single downloads array.

Error handling

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

try {
    await client.models.run("dragon-cup", { outputs: { formats: ["gltf"] } });
} catch (err) {
    if (err instanceof BitbybitApiError) {
        console.error(err.code, err.message, err.statusCode);
    }
}

Documentation

Full guides with examples for every endpoint:

• SDK Overview - setup, polling, error handling, type imports
• Models - parametric model generation and batch runs
• CAD Operations - execute, pipeline, compound
• Conversion - STEP → glTF with simple and advanced options
• Tasks - task lifecycle management
• Files - file upload and management
• API Reference - full OpenAPI endpoint reference

Use It With an AI Agent

Two MCP servers put this API in front of an AI coding agent, and they answer different questions.

The free Bitbybit CAD MCP documents the geometry API: every operation you can name in a pipeline, with its parameters, defaults, return type and examples, for the exact version you use. Connect it while the agent writes SDK calls, so it stops inventing operation names:

claude mcp add --transport http bitbybit https://mcp.bitbybit.dev/mcp

The Bitbybit CAD Cloud MCP takes your API key and runs the same work this SDK runs - operations, pipelines, models, STEP to glTF conversions - straight from the conversation, returning the results as download links:

claude mcp add --transport http bitbybit-cloud https://api.bitbybit.dev/mcp --header "X-API-Key: <your key>"

Every execution is metered on the key's plan exactly as an SDK call would be, and the key's scopes decide which tools the agent even sees. Cursor, VS Code, claude.ai and ChatGPT connect to both - every configuration is here, and the AI section of the documentation explains when each server is the right one.

Working examples

• Node.js + SDK - Express server with Three.js frontend
• Hono + SDK - Cloudflare Workers with Three.js frontend

Requirements

• Node.js 18+ (or any runtime with native fetch)
• A Bitbybit API key - get one at bitbybit.dev/auth/pick-plan

This package is part of the Bitbybit monorepo.

License

MIT