Skip to main content

New to APIs?

This page is for people who have never used an API before. If you already write software, skip to the Quick Start Guide.

What an API is​

An API is a way for one program to ask another program to do something. Instead of a person opening a website, clicking Upload, and reading the result on screen, a program sends the same request over the internet and gets the answer back as data it can use.

The Toolpath application at app.toolpath.com is a website a person uses. The Toolpath Engine API is the same underlying capability, exposed so that your software can use it — your quoting tool, your ERP, your internal shop app, or a spreadsheet script.

What the Toolpath API does today​

You give it a CAD file. It gives you back a structured description of the part's manufacturing geometry — design-for-manufacturability (DFM) information. That is the whole of what the API does at present.

The result comes from Toolpath's part comprehension engine, the same technology behind the Toolpath application. The API does not measure the file in any general-purpose way; it reads the part the way a manufacturing engineer would, which is why the results come back as recognized features and machining directions rather than as raw geometry.

In practice it recognizes the features in the part — pockets, holes, walls, floors, and so on — along with the directions the part can be approached from and the surfaces each feature covers. It also returns a rendered thumbnail image and a 3D mesh you can display. For any feature you can then ask for feature details, which add machining information: how deep the feature runs along the tool axis, how much material is intentionally left for a later operation, tolerance bands, and the areas machined wall-wise versus floor-wise.

What is coming later​

The Engine API is expanding beyond DFM. Tool matching, estimating, quoting, and CAM APIs are planned, but not yet available today.

The API Reference is generated from the live API, so it always shows exactly what exists. If an operation is not listed there, it has not shipped yet.

What you need before you start​

Three things:

  1. An account, created at the Toolpath API Portal.
  2. An API key, generated from that account.
  3. Somewhere to run code — a laptop with Python or Node.js installed is plenty.

The Quick Start Guide walks through the first two. They take about five minutes and no programming.

What an API key is​

An API key is a long password for programs. Your key identifies your organization and proves your software is allowed to make requests, the same way signing in proves it in a browser. Toolpath keys begin with tp_.

Treat it exactly as you would a password. Do not put it in a file you share, do not commit it to a code repository, do not paste it into a screenshot or a chat window, and do not put it in anything that runs inside a customer's browser. If a key gets out, revoke it in the Portal and create a new one — any team member can revoke, and it takes effect immediately.

Where to keep it: a password manager. Any reputable one will do. They are encrypted, they sync to your other devices, and they offer shared vaults for when a teammate needs the same key. Save the key there the moment you create it, because Portal shows it only once and cannot recover it later.

Where not to keep it: a text file on your desktop, a note app, an email to yourself, a chat message, or a spreadsheet. Those are the places keys leak from.

Keeping a key and using a key are different things. The password manager is your record of it. When you write code, the script should read the key from an environment variable rather than have it typed into the file — Authentication shows how, and the AI tools section below explains why it matters if you ever share your code.

How a request actually works​

Every request to the Engine API is an ordinary web request with your key attached. The answers come back as JSON — plain text arranged in labelled fields, which every programming language can read.

Processing a part takes four steps:

  1. Create the part. You tell the API a file is coming. It answers with an ID for the part and a temporary web address to upload to.
  2. Upload the CAD file to that address. The file itself does not go through the API; it goes straight to storage. Your API key must not be attached to this upload — the address is already authorized, and adding the key can cause the upload to be rejected.
  3. Request processing. This returns immediately with a job ID. It does not wait for the work to finish.
  4. Get the part once the job completes.

Step 3 is the part that surprises newcomers. Processing is asynchronous: the API accepts the work and answers straight away, and the actual computation happens afterwards. So your program has to wait for it. There are two ways — you can ask repeatedly until the part is ready (polling), or you can hold a connection open and let the API push updates as the job progresses. The reference in SDK usage examples shows both.

The other thing worth knowing early: the thumbnail, mesh, and download links in a part response expire after 15 minutes. They are for fetching right away, not for storing in a database.

See it working first​

Before writing anything, it helps to see a finished application built on the API. Toolpath's reference implementation is at dfm.toolpath.com — a complete, working example of what the Engine API supports end to end. Open it and run a part through it, and you will have watched the whole flow this page describes without writing a line of code.

This walkthrough shows what it does:

Seeing a reference implementation work is the single fastest way to understand an API. It shows you the order the calls are made in, what the responses really look like, and what a sensible application does with them.

Using AI tools to help you build​

If you are not a programmer, an AI assistant — Claude, ChatGPT, Copilot, or similar — can realistically get you from nothing to a working script. These tools are good at exactly this task, because the API is documented in a machine-readable form they can read directly.

First, give the assistant the API reference​

This is the step that makes the difference, and it is the one people skip. An assistant working from memory will guess at how the Engine API works and get it wrong. An assistant that has been handed the actual reference will write code against real endpoints.

The Engine API publishes an OpenAPI document: a single file that formally describes every operation, every field, and every response. It is public, needs no API key, and lives at api.toolpath.com/v1/openapi.json. It is about 80 KB — small enough for any current assistant to read in full.

There are three ways to hand it over. Use whichever matches the tool you are using:

Paste the link and ask the assistant to read it. Works with any tool that can browse the web.

Please fetch and read https://api.toolpath.com/v1/openapi.json — it is the OpenAPI specification for the Toolpath Engine API. I want to write code against it.

If the tool cannot browse, it will tell you, or it will answer without having read anything. Ask it to confirm: "How many operations are in that specification?" If it cannot tell you, it did not read the file, and you should use one of the next two methods instead.

Attach the file. Open the link in your browser, save the page (Ctrl+S or Cmd+S) as openapi.json, and attach it to the conversation the way you would attach a document. This is the most reliable method, and the right one for tools without web access. Pasting the contents into the message also works, but an attachment is cleaner and less likely to be truncated.

Save it into your project folder. If you are using a coding assistant that works inside a folder on your computer — Claude Code, Cursor, Copilot and similar — download the file into that folder. The assistant will find and read it as it works, with no further prompting.

Or start from the open-source Toolpath application​

Want a working app to adapt instead? A fork is your own GitHub copy of the open-source Toolpath repository. Click Fork on GitHub, then clone your copy to your computer:

git clone https://github.com/your-name/toolpath.git
cd toolpath

Open that folder in your coding assistant. It can use the existing screens, API calls, and project conventions instead of starting from scratch. Start with a prompt like this:

Read the README and existing Engine API integration. Using this codebase and the OpenAPI specification, add [describe your goal]. Work on a new Git branch, keep my API key out of the repository, and explain how to run and test the change.

Keep API keys only in the local environment file the repository documents — never in source code, commits, or an AI chat.

Keeping your fork up to date​

Your fork's origin is your GitHub copy; upstream is Toolpath's original repository. Add upstream once:

git remote add upstream https://github.com/toolpath/toolpath.git

Make your own changes on a branch, not main:

git switch -c add-my-feature

When that work is committed or set aside, sync main with the original project:

git switch main
git fetch upstream
git merge --ff-only upstream/main
git push origin main

If the merge stops, do not force it. Your changes need a deliberate merge; ask someone comfortable with Git to review the conflict. GitHub's Sync fork button can update a clean fork in the browser.

Point the assistant at these documentation pages too. The specification tells it the exact shape of every request; pages like the Quick Start Guide tell it why the steps happen in the order they do. Both together give much better results than either alone.

Prompts that work​

Say what you want to end up with, not how to build it. Name the outcome, the language, and what you are starting from. Compare:

❌ "How do I use the Toolpath API?"

✅ "Using the attached OpenAPI specification, write a Python script that uploads a STEP file from my computer, waits for the analysis to finish, and prints every recognized feature with its type. Read the API key from an environment variable called TOOLPATH_API_KEY."

The first invites a vague summary. The second describes a finished thing, so you get something you can actually run.

Tell it to stay inside the specification. This is the single most useful sentence you can add, because it targets the failure mode described below:

Only use endpoints and fields that appear in the specification I gave you. If something I ask for is not supported, say so instead of inventing it.

Ask for one step at a time. Rather than requesting the whole program, build it in stages: first a script that just confirms the key works, then one that uploads a file, then one that waits for the part. Run each before asking for the next. Five verified stages are far easier to fix than a hundred lines that fail all at once.

Paste errors back verbatim. The full error text — not a summary of it — is usually enough for the assistant to find the problem immediately. Include the code you ran alongside it.

Ask it to explain its own output. "What does this line do?" and "What happens if the file is too large?" are fair questions and a fast way to learn. Understanding roughly what your script does is what lets you tell a real problem from a cosmetic one.

Ask it to check its work against the reference. Once you have something that runs:

Go back through this script and check every endpoint, parameter, and field name against the specification. List anything that does not match.

Three cautions:

  • Never paste your API key into an AI tool. Have the script read the key from an environment variable instead, and ask the assistant to write it that way. Treat a chat window as public: anything you type into one may be retained, logged, or resurface in a later session. A key that has been pasted into a chat should be considered compromised — regenerate it in Portal rather than hoping it went unnoticed.
  • AI tools invent things that do not exist. A model may confidently produce an endpoint, a field, or an option that was never in this API — often something that sounds entirely plausible. The API Reference is the authority. If the generated code refers to something not documented there, it is wrong, no matter how convincing it sounds.
  • Check the result, not just that it ran. Code can execute cleanly and still be wrong. Try a part you already know and confirm the answer matches what you expect before trusting it on anything real.

Where to go next​

  1. Quick Start Guide — create your account and your first API key.
  2. Authentication — how to attach the key to a request.
  3. SDK installation — the TypeScript client and UI packages; a Python pip package is coming soon.
  4. SDK usage examples — complete working code for the whole flow.
  5. API Reference — every operation and field, in full detail.

Getting help​

If you get stuck, email Toolpath Support at support@toolpath.com.

The most useful thing you can send is the exact request you made and the exact error you got back, pasted in full rather than described. The API returns a machine-readable code and a human-readable explanation with every failure, and those two things are usually enough to identify the problem straight away. Leave your API key out of the email — support never needs it.