Onshape Developer Documentation

https://onshape-public.github.io/docs/
Admin
Onshape Developer Documentation provides REST API resources and guides for developing applications...
Tokens:266,888
Snippets:1,319
Trust Score:8.3
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install Flask and requests_oauthlib (Python)

Source: https://onshape-public.github.io/docs/auth/oauth

Installs the required Python packages for the Flask OAuth example.

```bash
pip3 install flask
pip3 install requests_oauthlib
```

--------------------------------

### Install Passport and passport-onshape

Source: https://onshape-public.github.io/docs/auth/oauth

Install the required npm packages for authentication.

```bash
npm install passport
npm install passport-onshape
```

--------------------------------

### Add Basic Authorization header with example credentials

Source: https://onshape-public.github.io/docs/auth/apikeys

Example header using a base-64-encoded credential string for Basic Authorization.

```bash
-H 'Authorization: Basic ZnBpZnE1cm92d2VjeHZRU0k0MmxHbn0m4r5ydXNXczRPRUJLWTduS1NObVhoMzlrN2dzVE5QWEdqb0gzSUU4dFVnTlREdDZaYQ==' \

```

--------------------------------

### Install requests module (Windows)

Source: https://onshape-public.github.io/docs/api-intro/quickstart

Install the requests module using pip on Windows. If pip is not installed, use the alternative command shown in the source.

```bash
py -m pip install requests

```

--------------------------------

### List Example: Intermediate Step 2 - Change

Source: https://onshape-public.github.io/docs/app-dev/structuredstorage

Intermediate step 2 of the list example: change.

```json
   {"myKey": ["firstValue", "secondValue"]}
```

--------------------------------

### Encoded configuration example (input)

Source: https://onshape-public.github.io/docs/api-adv/configs

Example JSON input for encoding a configuration. Shows a parameter with ID 'List_izOjbm5HCRXEld' and value '_500_mm'.

```json
{
    "parameters": [
        {
        "parameterId": "List_izOjbm5HCRXEld",
        "parameterValue": "_500_mm"
        }
    ]
}
```

--------------------------------

### Encoded configuration example (output)

Source: https://onshape-public.github.io/docs/api-adv/configs

Example output from encoding a configuration. Shows the encodedId and queryParam values.

```json
{
    "encodedId": "List_sCW2T7xBCmN6an=_500_mm",
    "queryParam": "configuration=List_izOjbm5HCRXEld%3D_500_mm"
}
```

--------------------------------

### Base-64 encode example API keys on MacOS

Source: https://onshape-public.github.io/docs/auth/apikeys

Example command for MacOS using the provided sample access key and secret key. The output is a base-64-encoded string used as credentials.

```bash
printf abcdefghi0123456789jkl:abcdefghijklmnopqrstuvwxzy0123456789abcdefghijkl | base64

```

--------------------------------

### List Example: Intermediate Step 1 - Insertion

Source: https://onshape-public.github.io/docs/app-dev/structuredstorage

Intermediate step 1 of the list example: insertion.

```json
   {"myKey":  "myValue"}
```

--------------------------------

### Get configuration data (getConfiguration)

Source: https://onshape-public.github.io/docs/api-adv/configs

Retrieves the configuration data for a Part Studio or Assembly. Uses GET request to the configuration endpoint. Requires authentication.

```bash
curl -X 'GET' \
    'https://cad.onshape.com/api/v6/elements/d/{did}/wvm/{wvmid}/e/{eid}/configuration' \
    -H 'Accept: application/json;charset=UTF-8; qs=0.09' \
    -H 'Authorization: Basic CREDENTIALS'\
    -H 'Content-Type: application/json;charset=UTF-8; qs=0.09'
```

--------------------------------

### Part Response Example with partId

Source: https://onshape-public.github.io/docs/api-adv/translation

Example response from Part/getPartsWMV showing the FLYWHEEL part with partId 'JiD'. Use the partId field to export the part.

```json
[
  ...
  {
    "name" : "FLYWHEEL",
    "state" : "IN_PROGRESS",
    "propertySourceTypes" : {
      "57f3fb8efa3416c06701d60f" : 3,
      "57f3fb8efa3416c06701d60d" : 3,
      "57f3fb8efa3416c06701d61e" : 3,
      "57f3fb8efa3416c06701d60e" : 3,
      "57f3fb8efa3416c06701d60c" : 3
    },
    "defaultColorHash" : "FzHLKqGeuTBFjmY_2_0",
    "ordinal" : 1,
    "isMesh" : false,
    "description" : "Flywheel",
    "microversionId" : "bdb504d2d4c948493a87ccf3",
    "partNumber" : "PRT-10241",
    "elementId" : "6bed6b43463f6a46a37b4a22",
    "partId" : "JiD",
    "bodyType" : "solid",
    "customProperties" : {
      "57f3fb8efa3416c06701d61e" : "false"
    }
  ...
]
```

--------------------------------

### Export configured part - redirect URL example

Source: https://onshape-public.github.io/docs/api-adv/configs

Example redirect URL returned by the export endpoint. Navigate to this URL in a browser to download the export.

```text
https://cad.onshape.com/api/v6/partstudios/d/e60c4803eaf2ac8be492c18e/w/d2558da712764516cc9fec62/e/958bceb5a2511b572dbbe851/parasolid?includeExportIds=false&configuration=List_izOjbm5HCRXEld%253D_500_mm&binaryExport=false
```

--------------------------------

### Get Top plane ID with evalFeatureScript

Source: https://onshape-public.github.io/docs/api-adv/fs

Example curl call to get the ID of the Top plane using the evalFeatureScript endpoint. Replace URL parameters and CREDENTIALS as needed.

```bash
curl -X 'POST' \
  'https://cad.onshape.com/api/v8/partstudios/d/{did}/w/{wid}/e/{eid}/featurescript?rollbackBarIndex=-1' \
  -H 'Accept: application/json;charset=UTF-8; qs=0.09' \
  -H 'Authorization: Basic CREDENTIALS' \
  -H 'Content-Type: application/json;charset=UTF-8; qs=0.09' \
  -d '{
        "script": "function(context is Context, queries) { return transientQueriesToStrings(evaluateQuery(context, qCreatedBy(makeId(\"Top\"), EntityType.FACE))); }"
}'
```

--------------------------------

### Get elements in a document - Response

Source: https://onshape-public.github.io/docs/api-adv/documents

Example response from the getElementsInDocument endpoint. Shows a code block for each tab, including 'ENG_BLOCK' and 'CRANK' with their IDs and types.

```json
[
  {
    "name": "ENG_BLOCK",
    "id": "9ff7abbba6852dc4d0bce252",
    "type": "Part Studio",
    "elementType": "PARTSTUDIO",
    ...
  },
  {
    "name": "CRANK",
    "id": "6bed6b43463f6a46a37b4a22",
    "type": "Part Studio",
    "elementType": "PARTSTUDIO",
    ...
  }
  ...
]
```

--------------------------------

### applicationInit

Source: https://onshape-public.github.io/docs/app-dev/messages/drawings-msg

Send once on application startup to initialize the extension within the drawing context.

```APIDOC
## applicationInit

### Description
Send once on application startup to initialize the extension within the drawing context.

### Message Name
`applicationInit`

### Message Structure
```
message = {
  documentId: documentId,
  workspaceId: workspaceId,
  elementId: elementId,
  messageName: 'applicationInit'
}
```

### Parameters
- **documentId** (string) - Required - The document ID.
- **workspaceId** (string) - Required - The workspace ID.
- **elementId** (string) - Required - The element ID.
- **messageName** (string) - Required - Must be `'applicationInit'`.
```

--------------------------------

### Get part ID from getPartsWMVE response

Source: https://onshape-public.github.io/docs/api-adv/metadata

Example response from the getPartsWMVE endpoint showing a part with ID 'JHD'. This ID is used in subsequent metadata calls.

```json
{
  "name": "Main",
  // ...
  "microversionId": "{mid}",
  "partNumber": null,
  "elementId": "{eid}",
  "partId": "JHD",
  "bodyType": "sheet",
  // ...
}
```

--------------------------------

### Metadata response JSON

Source: https://onshape-public.github.io/docs/api-adv/metadata

Example response from the GET metadata call. Shows the Name property with value 'NEW_PART' and a propertyId placeholder. The propertyId is needed for the update call.

```json
{
  "jsonType": "metadata-element",
  "elementType": 0,
  "mimeType": "onshape/partstudio",
  "elementId": "{eid}",
  "properties": [
    {
      "name": "Name",
      "value": "NEW_PART",
      "validator": {},
      "required": true,
      "editable": true,
      "propertyId": "{propertyId}",
      // ..
    }, // ...
  ], // ...
}
```

--------------------------------

### Send initialization message and handle post messages

Source: https://onshape-public.github.io/docs/app-dev/clientmessaging

Example of sending an applicationInit message to the Onshape client and handling incoming messages with origin verification. Note: proper cleanup of event listeners is not included.

```javascript

function handlePostMessage(event) {
  // ensure that the event data is from a legit source:
  if(theServerStringFromActionUrl !== event.origin) {
    console.error('origin of message is not legitimate');
    return;
  }

  // branch based on messageName attribute
  switch(event.data.messageName) {
    case 'SELECTION':
      console.debug('SELECTION event data: %o', event.data);
      break;
    default:
      console.debug(`${event.data.messageName} not handled`);
    }
}

window.addEventListener('message', handlePostMessage);

const initMessage = {
  documentId:  theDocumentId,    // required - parsed from action url
  workspaceId: theWorkspaceId,   // required - parsed from action url
  elementId:   theElementId,     // required - parsed from action url
  messageName: 'applicationInit' // required
};

window.parent.postMessage(initMessage, '*');

```

--------------------------------

### Create Instance with POST /assemblies/d/{targetDid}/w/{targetWid}/e/{targetEid}/instances

Source: https://onshape-public.github.io/docs/api-adv/assemblies

Inserts an instance of a part, sketch, assembly, or Part Studio into an assembly. The request body specifies the source document, element, and instance properties.

```bash
curl -X 'POST' \
    'https://cad.onshape.com/api/v9/assemblies/d/{targetDid}/w/{targetWid}/e/{targetEid}/instances' \
    -H 'Accept: application/json;charset=UTF-8; qs=0.09' \
    -H 'Authorization: Basic CREDENTIALS' \
    -H 'Content-Type: application/json;charset=UTF-8; qs=0.09' \
    -d '{
        "configuration": "string",
        "documentId": "{sourceDid}",
        "elementId": "{sourceEid}",
        "featureId": "string",
        "includePartTypes": [
            "PARTS"
        ],
        "isAssembly": true,
        "isHidden": true,
        "isSuppressed": true,
        "isWholePartStudio": true,
        "microversionId": "string",
        "partId": "string",
        "partNumber": "string",
        "revision": "string",
        "versionId": "{sourceEid}"
        }'

```

--------------------------------

### cURL request to search documents

Source: https://onshape-public.github.io/docs/api-adv/documents

cURL command to call the GET /api/v10/documents endpoint with query parameters to search for the 'Onshape API Guide' document. Requires authentication via Basic credentials.

```bash
curl -X 'GET' \
'https://cad.onshape.com/api/v10/documents?q=Onshape%20API%20Guide&filter=7&owner=629677dbd020f032bea73ef7&ownerType=1&sortColumn=createdAt&sortOrder=desc&offset=0&limit=1' \
  -H 'Accept: application/json;charset=UTF-8; qs=0.09' \
  -H 'Authorization: Basic {credentials}' \
  -H 'Content-Type: application/json;charset=UTF-8; qs=0.09'
```

--------------------------------

### Get assembly definition response with instance IDs

Source: https://onshape-public.github.io/docs/api-adv/assemblies

Example response from the getAssemblyDefinition endpoint showing instance IDs and suppression states. Use the instance IDs (e.g., instanceIdPartOne, instanceIdPartTwo) in the assembly modify request body.

```json
{
  "rootAssembly": {
    // json truncated
    "instances": [
      {
        "isStandardContent": false,
        "type": "Part",
        "id": "instanceIdPartOne", // copy this ID
        "name": "Part 1 <1>",
        "suppressed": true, // Part 1 is suppressed
        "partId": "JHD",
        "fullConfiguration": "default",
        "configuration": "default",
        "documentId": "did",
        "elementId": "eid",
        "documentMicroversion": "mid"
      },
      {
        "isStandardContent": false,
        "type": "Part",
        "id": "instanceIdPartTwo", // copy this ID
        "name": "Part 2 <1>",
        "suppressed": false, // Part 2 is unsuppressed
        "partId": "JHH",
        "fullConfiguration": "default",
        "configuration": "default",
        "documentId": "did",
        "elementId": "eid",
        "documentMicroversion": "mid"
      }
    ],
    "fullConfiguration": "default",
    "configuration": "default",
    "documentId": "did",
    "elementId": "eid",
    "documentMicroversion": "mid"
  }
  // json truncated
}
```

--------------------------------

### Create a cube feature with addPartStudioFeature

Source: https://onshape-public.github.io/docs/api-adv/partstudios

POST request to add a feature to a Part Studio. This is a POST to the same endpoint as the GET example. The request body contains JSON of feature data, which for a cube feature would include the 'cube' feature type and a side length parameter.

```bash
curl -X 'POST \
  'https://cad.onshape.com/api/v9/partstudios/d/{did}/{wvm}/{wvmid}/e/{eid}/features' \
  -H 'Authorization: Basic CREDENTIALS' \
  -H 'Accept: application/json;charset=UTF-8; qs=0.09'\
  -H 'Content-Type: application/json;charset=UTF-8; qs=0.09' \
  -d '{
          <JSON of feature data>
      }'
```

--------------------------------

### applicationInit message

Source: https://onshape-public.github.io/docs/app-dev/element-right-panel

Sent once on application startup to initialize the extension.

```json
message = {
    documentId: documentId,
    workspaceId: workspaceId,
    elementId: elementId,
    messageName: 'applicationInit'
}
```

--------------------------------

### Install requests module (MacOS)

Source: https://onshape-public.github.io/docs/api-intro/quickstart

Install the requests module using pip on macOS. If pip is not installed, use the alternative command shown in the source.

```bash
python3 -m pip install requests

```

--------------------------------

### Base-64 encode example API keys on Windows

Source: https://onshape-public.github.io/docs/auth/apikeys

Example PowerShell command for Windows using the provided sample access key and secret key. The output is a base-64-encoded string used as credentials.

```powershell
powershell "[convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(\"abcdefghijklmnopqrstuvwxzy0123456789abcdefghijkl:abcdefghijklmnopqrstuvwxzy0123456789abcdefghijkl\"))"

```

--------------------------------

### cURL: Get document name with GET request

Source: https://onshape-public.github.io/docs/api-intro/quickstart

Uses cURL to send a GET request to the Onshape API endpoint. Requires your credentials for Basic authentication. Returns the document JSON, including the 'name' property.

```bash
curl -X 'GET' \
https://cad.onshape.com/api/v10/documents/e60c4803eaf2ac8be492c18e \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json;charset=UTF-8; qs=0.09' \
  -H 'Authorization: Basic CREDENTIALS'
```

--------------------------------

### applicationInit message

Source: https://onshape-public.github.io/docs/app-dev/messages/drawings-msg

Send once on application startup to initialize the extension within the drawing context.

```javascript
message = {
  documentId: documentId,
  workspaceId: workspaceId,
  elementId: elementId,
  messageName: 'applicationInit'
}
```

--------------------------------

### GET /api/billing/plans/client/<client id>

Source: https://onshape-public.github.io/docs/api-adv/billing

Gets a list of the billing plans defined for the specified client.

```APIDOC
## GET /api/billing/plans/client/<client id>

### Description
Get a list of the billing plans defined for this client.

### Method
GET

### Endpoint
/api/billing/plans/client/<client id>

### Parameters
#### Path Parameters
- **client id** (string) - Required - The client ID for which to retrieve billing plans.

### Response
#### Success Response (200)
- **plans** (array) - List of billing plan objects.
```

--------------------------------

### index.html - Hello World button page

Source: https://onshape-public.github.io/docs/app-dev/helloworld

HTML page that displays a 'Click Me' button. It loads script.js to handle the button click and send the 'showMessageBubble' message to Onshape.

```html
<!DOCTYPE html>
<html lang="en">
<body>
    <main>
        <p>Click the button below to send the `showMessageBubble` message to Onshape, which displays "Hello World!" in a blue bubble.</p>
        <button id="showMessageBubble">Click Me</button>
    </main>
    <script src="script.js"></script>
</body>
</html>

```

--------------------------------

### GET /api/v6/drawings/modify/status/{mrid}

Source: https://onshape-public.github.io/docs/api-adv/drawings

Gets the status of a drawing modification. Provide the modification ID from the modifyDrawing response.

```APIDOC
## GET /api/v6/drawings/modify/status/{mrid}

### Description
Gets the status of a drawing modification. Provide the modification ID from the modifyDrawing response.

### Method
GET

### Endpoint
https://cad.onshape.com/api/v6/drawings/modify/status/{mrid}

### Parameters
#### Path Parameters
- **mrid** (string) - Required - Modification ID (from modifyDrawing response)

### Request Example
```
curl -X 'GET' \
  'https://cad.onshape.com/api/v6/drawings/modify/status/{mrid}' \
  -H 'Authorization: Basic CREDENTIALS' \
  -H 'Accept: application/json;charset=UTF-8; qs=0.09' \
  -H 'Content-Type: application/json;charset=UTF-8; qs=0.09'
```

### Response
#### Success Response (200)
- **requestState** (string) - Status of the modification: ACTIVE, DONE, or FAILED
- **annotationIds** (array) - Unique IDs of annotations created or edited

#### Response Example
```
{
  "requestState": "DONE",
  "annotationIds": ["string"]
}
```
```

--------------------------------

### script.js - Onshape Hello World application extension

Source: https://onshape-public.github.io/docs/app-dev/helloworld

This JavaScript file parses the Onshape URL to extract document, workspace, and element IDs. It initializes the app by sending an 'applicationInit' message and sends a 'showMessageBubble' message with 'Hello World!' when the button is clicked.

```javascript
/**
 * Extracts Onshape document, workspace, and element IDs from a given URL.
 * Supports both query parameter format and Onshape path-based URL format.
 *
 * @param {string} currentURL - The full URL string to parse.
 * @returns {{ documentId: string, workspaceId: string, elementId: string }} An object containing the three Onshape IDs.
 * @throws {Error} If the required IDs cannot be found in the URL.
 */
function getOnshapeIdsFromUrl(currentURL) {
    const url = new URL(currentURL);
    const params = url.searchParams;

    const documentId = params.get('documentId');
    const workspaceId = params.get('workspaceId');
    const elementId = params.get('elementId');

    if (documentId && workspaceId && elementId) {
        return { documentId, workspaceId, elementId };
    }

    const pathMatch = url.pathname.match(/\/documents\/([^/]+)\/(?:w|v|m)\/([^/]+)\/e\/([^/]+)/);

    if (pathMatch) {
        return {
            documentId: pathMatch[1],
            workspaceId: pathMatch[2],
            elementId: pathMatch[3]
        };
    }

    throw new Error('Missing Onshape IDs in URL. Provide documentId, workspaceId, and elementId as query parameters or use an Onshape document URL.');
}

/**
 * Initializes the Hello World application once the DOM is fully loaded.
 *
 * This handler performs the following steps:
 * 1. Parses Onshape document, workspace, and element IDs from the current
 *    page URL using {@link getOnshapeIdsFromUrl}.
 * 2. Sends an `applicationInit` message to the Onshape parent frame
 *    to signal that the app is ready.
 * 3. Attaches a click listener to the button that sends a `showMessageBubble` 
 *    message with the text "Hello World!" to the parent frame.
 *
 * @listens Document#DOMContentLoaded
 */
document.addEventListener('DOMContentLoaded', function() {

    // Get reference to the button.
    const showMessageBubble = document.getElementById('showMessageBubble');

    // Get reference to the parsed IDs.
    const { documentId, workspaceId, elementId } = getOnshapeIdsFromUrl(window.location.href);
    console.log('Onshape IDs:', { documentId, workspaceId, elementId });

    // Send applicationInit message
    const appInitMessage = {
        documentId: documentId,
        workspaceId: workspaceId,
        elementId: elementId,
        messageName: 'applicationInit'
    };
    window.parent.postMessage(appInitMessage, '*');

    // On button click, send showMessageBubble message and display 'Hello World!' to user.
    showMessageBubble.addEventListener('click', function() {
        const message = {documentId: documentId,
                     workspaceId: workspaceId,
                     elementId: elementId,
                     messageName: 'showMessageBubble',
                     message: 'Hello World!'};
        window.parent.postMessage(message, '*');
    });
});

```

--------------------------------

### createPartStudio: Create a new Part Studio tab

Source: https://onshape-public.github.io/docs/api-adv/partstudios

Creates a new Part Studio tab in a document. Requires authentication and uses the document ID and workspace ID in the URL.

```bash
curl -X 'POST' \
    'https://cad.onshape.com/api/v9/partstudios/d/{did}/w/{wid}' \
    -H 'Accept: application/json;charset=UTF-8; qs=0.09' \
    -H 'Authorization: Basic CREDENTIALS' \
    -H 'Content-Type: application/json;charset=UTF-8; qs=0.09' \
    -d '{
        "name": "newPartStudioTabName"
        }'

```

--------------------------------

### startFirstViewCommand

Source: https://onshape-public.github.io/docs/app-dev/messages/element-tab

Sent to a drawings application extension when the drawing is created with zero views. For this example, we call the part, Part Studio, or assembly being drawn the item.

```APIDOC
## startFirstViewCommand

### Description
Sent to a drawings application extension when the drawing is created with zero views. For this example, we call the part, Part Studio, or assembly being drawn the `item`.

### Message
```json
{
  "messageName": "startFirstViewCommand",
  "documentId": "documentId", // document containing the item
  "workspaceId": "workspaceId", // sends workspaceId OR versionId of the item
  "versionId": "versionId", // sends workspaceId OR versionId of the item
  "elementId": "elementId", // ID of the element containing the item
  "elementName": "elementName", // name of the element containing the item
  "elementType": "partStudio | assembly | blob", // type of element containing the item
  "elementMicroversionId": "microversionId", // microversion ID of the element containing the item
  "itemType": "part | partStudio | assembly", // the item being drawn
  "partName": "partName", // if item is a part, the name of the part
  "idTag": "partId" // if item is a part, the part ID
}
```
```

--------------------------------

### GET /webhooks/{webhookId} - Get webhook

Source: https://onshape-public.github.io/docs/app-dev/webhook

Retrieves details for a specific webhook by its ID. Requires basic authentication.

```bash
curl -X 'GET' \
  'https://cad.onshape.com/api/v6/webhooks/webhookId' \
  -H 'Accept: application/json;charset=UTF-8; qs=0.09' \
  -H 'Authorization: Basic CREDENTIALS' 

```

--------------------------------

### Create Assembly with POST /assemblies/d/{did}/w/{wid}

Source: https://onshape-public.github.io/docs/api-adv/assemblies

Creates a new assembly tab in a document. Requires authentication and replaces {did} and {wid} with document and workspace IDs.

```bash
curl -X 'POST' \
    'https://cad.onshape.com/api/v9/assemblies/d/{did}/w/{wid}' \
    -H 'Accept: application/json;charset=UTF-8; qs=0.09' \
    -H 'Authorization: Basic CREDENTIALS' \
    -H 'Content-Type: application/json;charset=UTF-8; qs=0.09' \
    -d '{
        "name": "string"
        }'

```
Tokens:
Raw