Create Your First CAD Model with TypeScript

This quickstart shows you how to create your first CAD model from TypeScript with the Engine API. You will open a Modeling WebSocket, send commands that create a cube, color it green, and save the model as a STEP file.

The Engine API is the low-level modeling API behind Zoo Design Studio. It accepts typed modeling commands over a WebSocket and returns structured responses that you can use to build geometry, inspect results, and export files.

Note: There is an even easier way to connect to the Engine API: @kittycad/web-view. It lets you submit KCL directly and attach the live engine view to a <video> element with very little code. The rest of this quickstart uses the lower-level Modeling WebSocket so you can understand the fundamentals of what the helper library is doing.

What you will build

You will run a TypeScript script that creates a 20 mm cube, applies a green PBR material, and writes the exported model to green-cube.step.

Prerequisites

Before you start, make sure you have:

A Zoo account
Node.js 22 or newer installed on your computer
A terminal app, such as Terminal on macOS or Linux, or PowerShell on Windows

Get an API token

We will need an API token in order to use Zoo's services.

Generate an API token

Zoo uses an API token to verify that requests come from a particular account.

Keep your token private. Do not share it or commit it to source control.

Set your API token

Set your API token as the ZOO_API_TOKEN environment variable. The script reads this value and passes it to @kittycad/lib, which authenticates the Modeling WebSocket session.

On macOS or Linux, run:

On Windows PowerShell, run:

Create a TypeScript project

Create a folder for the quickstart and move into it.

On Windows PowerShell, macOS, or Linux, run:

This guide uses @kittycad/lib to create the API client, build the Modeling WebSocket URL, authenticate the session, serialize commands, parse responses, send modeling commands, and provide TypeScript types. Export responses are binary MsgPack messages, so the script uses @msgpack/msgpack to decode the exported STEP file. Node.js provides the native WebSocket runtime.

Write the script

Create a file named create_green_cube.ts and paste in this script:

Create and export the cube

Run the script:

The script opens a WebSocket to the Engine API, authenticates it with your API token, and sends modeling commands one at a time.

First, it creates a closed square path in the XY plane. Then it extrudes that path by the same distance as the square's side length, which creates a cube. The script reads the created body ID from the extrude response, uses that ID to set the cube's material color to green, and exports the body as STEP.

You should see output similar to:

Open the generated STEP file in Zoo Design Studio or another CAD tool to inspect the model.

Modeling command shape

The client sends each modeling command as a WebSocket request. For example, the STEP export command has this shape:

Each response includes the original cmd_id as request_id. The script uses that ID to match every response to the command that produced it. Most modeling responses are JSON text messages, while export responses are binary MsgPack messages that contain the exported file bytes.

Next steps

Now that you have sent your first Engine API commands, try changing the script:

Change CUBE_SIZE_MM to create a larger or smaller cube
Change the color values to apply a different material color
Add more path segments before the extrude command to create a new profile

For the full list of available modeling commands, see the Engine API reference.

Found a typo?