This page explains the basics of using the Onshape REST API. If you are brand new to using APIs, we suggest you spend some time learning the basics from these free resources:
Onshape uses REST APIs to communicate with clients and third-party systems. Onshape lives in your browser, which means you call REST APIs like you would any other web page. The API call returns information instead of a web page, and the response is formatted in JSON (JavaScript Object Notation).
You can use our REST APIs to access the Onshape engine and data in real time. We currently support three REST API requests (following the HTTP standards):
GET
: Retrieve (read) information from the server (i.e., your Onshape documents). Any arguments included in the URL are sent to the server.POST
: Update (write) the server with new information. Required data is included in the request body.DELETE
: Delete information from the server.A typical REST API call in Onshape includes five major components:
GET
, POST
, or DELETE
{base_url}/{fixed_url}
.{base_url}
: Onshape URL (i.e., https://cad.onshape.com/api
or https://companyName.onshape.com/api
for Enterprise accounts).{fixed_url}
: the URL of the API endpoint (more about this later)Content-Type
and Accept
.Content-Type
:application/json
Content-Type
will be application/octet-stream
Accept
: found under Media type
in the API response section on in the API Explorer.POST
requestsPOST
requests; optional for others.Since Onshape is a web-based solution, it uses a URL to define what is loaded in the browser.
Example Onshape URL:
https://cad.onshape.com/api/
documents/e60c4803eaf2ac8be492c18e/
w/d2558da712764516cc9fec62/
e/6bed6b43463f6a46a37b4a22
https://cad.onshape.com/api
is the base URL of the document.https://companyName.onshape.com/api
POST
requests are always made to a workspace, since versions and microversions are immutable.In this documentation, we often refer to the URL template as: {base_URL}/{endpoint}/d/{did}/{wvm}/{wvmid}/e/{eid}
or sometimes /{endpoint}/DWVME/
for short.
When your application is instantiated in a document, it is called with a URL like this:
https://_your-server.your-domain.com_?documentId=e60c4803eaf2ac8be492c18e&workspaceId=d2558da712764516cc9fec62&elementId=6bed6b43463f6a46a37b4a22&server=https%3A%2F%2Fcad.onshape.com&userId=53da35fbe4b0412c60b5e3b7&access=edit&debug=true
The query parameters passed from Onshape to your application are:
Parameter | Description |
---|---|
documentId | Current document ID |
workspaceId , versionId , microversionId | Current workspace ID OR version ID OR microversion ID |
elementId | Current (application) element ID |
server | The address of the current Onshape server. The server parameter is informational; REST requests should always be sent to cad.onshape.com . Enterprise accounts should be sent to companyName.onshape.com . |
userId | Current user ID, which can be found by calling /api/users/current and obtaining the user ID from the id field. |
access | Set to edit if the document should open with edit capabilities. |
The REST API in Onshape communicates data in JSON format. If you are new to working with JSON, we recommend the following resources:
The example below is the response from calling the getDocument
API for this public document. A lot of information is returned, so we’ve truncated the middle of the response below, but if we look at the very end of the resulting JSON, we can see that the response has correctly returned Onshape API Guide
as the document name
.
{
"jsonType": "document",
"documentThumbnailElementId": "",
"isUpgradedToLatestVersion": true,
"public": false,
"permission": "FULL",
"isOrphaned": false,
"recentVersion": null,
...
"isEnterpriseOwned": false,
"resourceType": "document",
"name": "Onshape API Guide",
"id": "e60c4803eaf2ac8be492c18e",
"href": "https://cad.onshape.com/api/v6/documents/e60c4803eaf2ac8be492c18e"
}
All endpoint calls are versioned. The version string is inserted directly after the /api/
path component. For instance, https://cad.onshape.com/api/v6/documents/e60c4803eaf2ac8be492c18e
indicates a version 6
request to the Onshape getDocument
endpoint.
Calls within a version are compatible with one another; typically this means that a GET request can be fed back in as a POST at the same version. Versions are incremented whenever Onshape introduces a non-backwards-compatible change. Onshape users should always refer to the latest version in their calls. If no version is specified, the oldest version (v0
) will be used.
The Onshape API generally uses the following conventions:
GET
for read-only operations, POST
for write operations, and DELETE
for deletions. Onshape does not currently support other methods, such as PUT
.D
Document ID (24-characters)W
Workspace ID (24-characters)V
Version ID (24-characters)M
Microversion ID (24-characters)E
Element ID (24-characters)/resource/context/subresource
. When present, the context identifies the document (D), the workspace, version or microversion (WVM), and the element (E). See the Onshape Architecture page for more information on Onshape’s basic API structure.Workspace
, Version
, and Microversion
forms for all appropriate GET
operations. POST
will always be to a Workspace
, as Versions
and Microversions
are immutable. Not all forms of all interfaces are implemented at this time.The following strings are valid unit designators:
For length measures:
meter
, meters
, m
millimeter
, millimeters
, mm
centimeter
, centimeters
, cm
inch
, inches
, in
foot
, feet
, ft
yard
, yards
, yd
For angular measures:
degree
, degrees
, deg
radian
, radians
, rad
Continue on to our API Explorer page to learn about about navigating the Onshape APIs in our Glassworks API Explorer.