AI for CAD Tools
What the Onshape API actually returns to an AI agent reading a document: version state, assembly structure, and where the permission check cuts it off.
·
⏱
8 min read
Michelle Ben-David
Michelle Ben-David is a mechanical engineer and Technion graduate. She served in an IDF elite technology and intelligence unit, where she developed multidisciplinary systems integrating mechanics, electronics, and advanced algorithms. Her engineering background spans robotics, medical devices, and automotive systems.
BOTTOM LINE
The Onshape API hands an agent a document’s structure, not its geometry: document, workspace, version, and microversion IDs; element types that determine what an assembly, part studio, or drawing tab contains; assembly structure as a queryable tree of parts and mates; and a release state tracked separately from whether the data exists at all. None of that requires opening the file in a browser. What it does require is treating workspaces as moving targets, versions as the stable reference point, release state as its own check rather than an inference, and permission as a boundary that can grant partial access through a linked document rather than a simple yes or no. An agent that respects those distinctions can answer real questions about an Onshape design. One that does not will eventually be confidently wrong about something a person would have caught by clicking around for ten seconds.
Connect an AI agent to an Onshape document and the assumption is usually that the agent now "sees the CAD model," the same way a person does after clicking the link. It does not. Onshape is API-first by design, and everything an agent gets back comes through the same REST interface any integration uses: documents, workspaces, versions, elements, and a permission check that runs on every single call. What that interface hands over, and what it deliberately withholds, decides whether an agent can answer a real question about a part or only fetch a name and a thumbnail.
This matters more for Onshape than for most CAD tools because there is no desktop file to fall back on. A SolidWorks or Inventor file can, in principle, be parsed locally, which is part of why a general-purpose assistant with no CAD-specific integration still struggles with those formats. An Onshape document has no local file at all: it lives entirely on Onshape’s servers, and the API is the only door in. Understanding what is on the other side of that door, document structure, version state, assembly data, and access control, is the actual engineering problem behind "connect an AI agent to Onshape."
What a Document Reference Actually Points To
An Onshape document ID identifies a container, not a design. That container holds one or more elements, and the element types are fixed: a Part Studio holds parametric features such as sketches and extrudes, an Assembly holds parts and sub-assemblies tied together with mates, a Blob stores an uninterpreted file such as a PDF or an image, an Application provides an iframe-based tab (Drawings are built this way), and a Feature Studio holds custom FeatureScript code. A document reference by itself says nothing about which of these an agent is about to read.
This is the first place a naive integration goes wrong. Handed a document link, it is tempting to assume "assembly" or "part" and query accordingly. The correct first call lists the elements in the document and their types, then routes the next call based on what actually comes back. A document can hold several elements of different types at once, one Part Studio for a machined bracket, an Assembly that places it, a Drawing element for the released print, and an agent that skips the listing step will occasionally ask an Assembly endpoint a Part Studio question and get an error that has nothing to do with permissions.
The identifiers involved are worth naming plainly, because every subsequent call depends on getting the right one. A document ID identifies the container. A workspace ID or version ID says which branch or snapshot to read from. An element ID picks the specific tab inside that document. All four are fixed-length strings with no inherent meaning beyond pointing at the right object, and mixing up which ID belongs in which slot of a request is a more common source of failed calls than any permission issue, the same category of plumbing that sits underneath any API-based integration that writes geometry back into a CAD system rather than just reading it.
IN PRACTICE
Leo uses a Large Mechanical Model trained on 1M+ technical sources. It also provides citations, so we don’t have to guess whether a material property or tolerance is correct. We see 96% accuracy on technical queries.
- Dorian G., AI Engineer
Workspaces vs Versions: Why the Distinction Matters to an Agent
Onshape tracks change through three layers: a workspace is an editable branch, a version is a named, immutable snapshot of one, and a microversion is the automatic checkpoint created after every individual edit inside a workspace. All three carry their own twenty-four-character identifiers, and an API call has to specify which one it is reading from.
This layered history is one of the clearer differences between Onshape’s cloud-native model and a desktop CAD system: there is no local save file whose timestamp an agent can trust, only workspaces, versions, and microversions tracked centrally on Onshape’s servers. A workspace is a moving target. Two calls to the same workspace ID, made a minute apart, can return different geometry if someone was editing in between, because a new microversion is created on every change. A version cannot change: once created, it is a fixed point that will return the same answer indefinitely. For a person clicking through the Onshape interface this distinction barely registers, since the browser just shows "current state." For an agent that needs a stable answer, or that is comparing a document to what it looked like at some earlier point, reading from a version rather than the active workspace is what keeps the answer from shifting under it mid-conversation.
Microversions sit underneath both, created automatically on every edit whether or not anyone chooses to name a version. They are the finest-grained record Onshape keeps, and an API call can read from one directly when it needs the exact state at a specific edit rather than the coarser granularity of a named version. Most agent workflows never need that level of precision, but it is there when a question turns on the difference between a state before and after one specific change rather than one release and the next.
Getting Assembly Structure Without Opening the File
An Assembly element exposes its structure as data: the parts and sub-assemblies it contains, the mate relationships connecting them, and the nesting of sub-assemblies inside other sub-assemblies. An agent can walk this tree the same way it would walk a bill of materials, without rendering a single triangle of geometry. That is enough to answer questions like which parts sit inside a given sub-assembly, how many instances of a fastener appear across the structure, or whether a particular part shows up more than once under different parents.
What that structure will not hand over on its own is intent. The API returns which parts are mated and how, not why a designer chose that mate type over another, and it returns part names and metadata, not the reasoning behind a tolerance or a material choice that might be sitting in a comment, a linked document, or someone’s memory. That gap is why most AI tools built for Onshape pair structural API access with a search layer over the surrounding documents rather than treating the assembly tree as the whole answer. Assembly structure through the API is a reliable map of what is connected to what. It is not a substitute for the design history that explains why.
Release State: What "Released" Means to an API Call
Onshape’s release workflow moves a candidate through a fixed set of states: In Progress for ordinary editable work, Pending while it awaits approval, Released once one or more approvers sign off (or the creator releases it directly), Rejected if an approver declines it, and Obsolete once a released object is retired. An agent reading a document through the API sees whichever of these states the object is currently in, and that state is not cosmetic. When a release candidate is approved, Onshape automatically creates a version and marks it as the immutable source of truth for that revision. Everything before that point was editable; after it, that specific version is frozen.
The practical consequence for an agent is that "this document exists" and "this document is released" are two different questions, and only one of them tells you whether a part is safe to reference in a downstream decision like ordering or manufacturing. A workspace sitting in Pending can look complete to an agent that only checks whether the geometry is there. Checking release state as its own field, rather than inferring it from the presence of data, is what keeps an agent from treating a candidate under review as if it had already cleared approval.
Where the Permission Boundary Actually Cuts Off Access
Permissions in Onshape do not always work the way a flat access-control list would suggest. A document that links to a second document grants any user who can already see the first one limited read access to the second, regardless of what permissions are set directly on that second document. That is useful for referenced parts and standard libraries, and it also means an agent walking a chain of linked documents can end up with partial visibility into something nobody explicitly shared with it, bounded by whatever that limited read grant actually covers.
This is the edge Leo is built to handle rather than paper over. Leo ingests Onshape document links as part of connecting to an organization’s CAD, PDM, and PLM systems, and when access to a linked document has been revoked or was never granted beyond that limited reference-level view, Leo returns a permission-aware error instead of silently returning nothing or, worse, surfacing a partial answer without flagging that it is partial. An agent that cannot tell the difference between "this document does not exist," "you don’t have access," and "you have limited access through a reference" will eventually give a confident answer built on a boundary it never actually cleared.
FAQ
See What Leo Can Pull From Onshape
Ask Leo about a linked Onshape document in plain language.
Leo connects to Onshape and other CAD, PDM, and PLM systems to search past designs, standards, and documents in plain language.
Schedule a Demo →
#1 New AI Software Globally - G2 2026
Enterprise-grade security
Trusted by world-class engineering teams
