Introduction to the Onshape REST API

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:

• https://docs.github.com/en/rest/guides/getting-started-with-the-rest-api
• https://www.freecodecamp.org/news/apis-for-beginners/

Videos & Courses

In addition to following along with the instructions on this page, you can also watch our Intro to the Onshape API videos below, or view the full course content in the Onshape Learning Center.

What is an API?

Video Key Takeaways

• Onshape is cloud-native; no files.
• You can access your Onshape data through the Onshape product interface, or using an API.
• APIs are common tools for cloud-based systems to communicate.
• Using the Onshape API can streamline many types of processes.

The Onshape Document Model

Video Key Takeaways

• Onshape documents are data containers.
• Onshape documents can contain parts, assemblies, subassemblies, drawings, and more.
• Work within an Onshape document is organized into branches; each branch contains a workspace and may contain versions.
• Onshape documents are organized into elements, such as Part Studios and assemblies.
• An Onshape document URL can point to a specific document, workspace, version, or element.
• Data security is Onshape’s highest priority.

REST APIs

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:

• Method:
  • GET, POST, or DELETE
  • Every Onshape API endpoint is labeled with its method type.
• URL:
  • Specifies the API endpoint and part of the document that the API is calling
  • Uses the following format: {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)
• Query parameters:
  • Optional parameters for the API call
  • Described in the drop-down content of every endpoint in the API Explorer (you’ll learn about using our API Explorer in a later section).
• Headers:
  • Defines the associated metadata, which is used by the server to process the request.
  • Usually contains Content-Type and Accept.
    • Content-Type:
      • Usually application/json
      • If the application downloads a file, Content-Type will be application/octet-stream
    • Accept: found under Media type in the API response section on in the API Explorer.
• Payload body:
  • Only applicable for POST requests
  • Required for some POST requests; optional for others.
  • Body template is available in the API drop-down in the API Explorer.
  • Typically obtained and modified from the response of a related GET request (rather than manually)

Onshape API Request

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.
  • Every Enterprise account has a custom base URL: https://companyName.onshape.com/api
• documents/ or d/ is followed by a 24-character document ID. The document ID uniquely identifies an Onshape document.
• Next, w/ is followed by a 24-character workspace ID. The workspace ID uniquely identifies a workspace within the document. By default, a document is started with the Main workspace.
  • To refer to a specific document version, replace w/ with v/, followed by the 24-character version ID.
  • With every edit made in the document, a microversion of every document is automatically created with every edit. To refer to a specific microversion, replace w/ with m/, followed by the 24-character microversion ID.
  • Note: POST requests are always made to a workspace, since versions and microversions are immutable.
• e/ is followed by a 24-character element ID. The element ID uniquely identifies an element (e.g., a tab that we see and access through the user interface).

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:

Onshape API Response

The REST API in Onshape communicates data in JSON format. If you are new to working with JSON, we recommend the following resources:

• https://www.w3schools.com/js/js_json_intro.asp
• https://www.freecodecamp.org/news/what-is-json-a-json-file-example/

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"
}

The Onshape API response also contains rate limiting information in the x-rate-limit-remaining header.

API Conventions

The Onshape API generally uses the following conventions:

• Onshape generally supports only 3 methods: GET for read-only operations, POST for write operations, and DELETE for deletions. Onshape does not currently support other methods, such as PUT.
• Strings should be UTF-8 encoded.
• Query parameters are used for optional parameters. All required parameters are included in the path. For brevity, we use the following upper case letters in path definitions in this document:
  • 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)
• The general form of a path is /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.
• Our intention is to provide 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.
• As of this writing, some API calls return information that is of use only for Onshape clients. You should generally only use the fields that are documented for external use. The internal data may be changed or removed without notice.

Versioning

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.

Unit Designators

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

What Now?

Continue on to our API Explorer page to learn about about navigating the Onshape APIs in our Glassworks API Explorer.