Skip to main content

SDK installation

@toolpath/api is a ready-made TypeScript client for the Engine API. Rather than building HTTP requests, setting headers, and picking apart JSON yourself, you call functions and get typed objects back — and the key handling described in Authentication is done for you on every request.

Using it is optional. The API is JSON over HTTPS, so anything that can make a web request can call it directly. The client saves you that boilerplate and keeps your code in step with the API as it changes.

It is generated from the same OpenAPI document as the API Reference, so its types match the published contract exactly. It also includes two helpers: one uploads a CAD file to the presigned URL returned when you create a part, and one waits for a job to finish.

TypeScript​

npm install @toolpath/api

Requires Node.js 20 or newer.

import { createToolpathClient, uploadToPresignedUrl, waitForJob } from '@toolpath/api'

const client = createToolpathClient({ apiKey: process.env.TOOLPATH_API_KEY! })
const part = await client.parts.createPart({ filename: 'bracket.step' })

await uploadToPresignedUrl(part.uploadUrl, cadFileBytes)
const processing = await client.parts.updatePart({ id: part.partId })
await waitForJob(client, processing.jobId)
const analyzed = await client.parts.getPart({ id: part.partId, jobId: processing.jobId })

waitForJob follows the job's event stream rather than asking for the job repeatedly. It resolves when the job succeeds and throws a JobFailedError when it fails — see Waiting for a job. Its reconnect option opens the stream again when it drops; a server watching many jobs at once should read Running a server that watches many jobs.

Building a user interface​

npm install @toolpath/viewer @toolpath/ui

For a React application, @toolpath/viewer renders an analyzed part's mesh, and @toolpath/ui provides Toolpath's React and Tailwind UI primitives. See each package's README for its required peer dependencies and setup.

Python​

The toolpath package is the generated Python client for the Engine API. It requires Python 3.11 or newer and is distributed as a wheel attached to a GitHub Release. Install it with uv; PyPI is not a distribution target.

Open the Python SDK releases and copy the release's uv add command for the toolpath (Python SDK) version you want. For example, version 0.9.0 installs with:

uv add "toolpath @ https://github.com/toolpath/ui-packages/releases/download/python-sdk-v0.9.0/toolpath-0.9.0-py3-none-any.whl"

The release notes include the matching command for each version. See the Python example for a complete part-analysis flow, and Waiting for a job for how to wait for a job to finish.

What the API client does not do​

It is a transport client. It exposes the documented operations and models directly and does not add a higher-level workflow of its own — there is no single call that uploads a part and returns a finished part. Sequencing the steps stays your code's job; waitForJob handles the waiting in between.

SDK usage examples shows that sequence written out in TypeScript and Python.