Assemblies

This page describes the APIs Onshape provides for working with assemblies.

Prerequisites

All Onshape API calls must be properly authenticated.
See the API Keys page for instructions and the Quick Start for an example.
All applications submitted to the Onshape App Store must authenticate with OAuth2.
For Standard accounts, replace {baseUrl} with cad in all endpoints. For Enterprise accounts, replace it with your company domain. Add /api and the version number, and then provide the endpoint.
https://{baseUrl}.onshape.com/api/v10/documents
https://cad.onshape.com/api/v10/documents
https://companySubDomain.onshape.com/api/v10/documents
Onshape IDs are written as: {did}, {wvmid}, {eid}, {pid}, {otherId}.
These represent document, workspace (or version or microversion), element, part, and other IDs, respectively.
Never include the braces {} with your IDs.
See API Guide: API Intro for information on what these IDs mean and how to obtain them from your documents.
This page provides sample code in cURL and python.
For additional instruction and video content, visit the Learning Center’s Intro to the Onshape API course.

Endpoints

createAssembly: Create a new assembly tab in a document.

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

getAssemblyDefinition: Get definition information for the assembly.

curl -X 'GET' \
    'https://cad.onshape.com/api/v9/assemblies/d/{did}/{wvm}/{wvmid}/e/{eid}?includeMateFeatures=false&includeNonSolids=false&includeMateConnectors=false&excludeSuppressed=false' \
    -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'

modify: Modify an assembly

curl -X 'POST' \
    'https://cad.onshape.com/api/v9/assemblies/d/{did}/w/{wid}/e/{eid}/modify' \
    -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 ' {
            "deleteInstances": [
                "string"
            ],
            "editDescription": "string",
            "suppressInstances": [
                "string"
            ],
            "transformDefinitions": [
                {
                "isRelative": true,
                "occurrences": [
                    {
                    "fullPathAsString": "string",
                    "headInstanceId": "string",
                    "occurrenceWithoutHead": "string",
                    "occurrenceWithoutTail": "string",
                    "parent": "string",
                    "path": [
                        "string"
                    ],
                    "rootOccurrence": true,
                    "tailInstanceId": "string"
                    }
                ],
                "transform": [
                    0
                ]
                }
            ],
            "unsuppressInstances": [
                "string"
            ]
        }

createInstance: Insert an instance of a part, sketch, assembly, or Part Studio into an assembly.

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

deleteFeature: Delete a feature from an assembly.

curl -X 'POST' \
    'https://cad.onshape.com/api/v9/assemblies/d/{did}/w/{wid}/e/{eid}/features/featureid/{fid}' \
    -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'

deleteInstance: Delete an instance from an assembly.

curl -X 'POST' \
    'https://cad.onshape.com/api/v9/assemblies/d/{did}/w/{wid}/e/{eid}/instance/nodeid/{nid}' \
    -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'

Sample Workflows

Create an assembly

Make a copy of this public document, and make a note of the copied document and workspace IDs in the URL.

Call the createAssembly endpoint. Specify a name for the new assembly tab in the request body; in this example, we’ll call it myNewAssembly.

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": "myNewAssembly"
    }'

Return to your document and observe that the new assembly tab has been added.

Insert a part into an assembly

Follow all steps in the Create an assembly tutorial.
In your copied document, open the PARTS tab folder, and then open the CRANK Part Studio. Make a note of the following IDs from the CRANK Part Studio:
- documentId - we’ll refer to this as our sourceDid for this example
- workspaceId - this is our sourceWid
- elementId of the CRANK Part Studio - this is our sourceEid

Call the getPartsWMVE endpoint to get the part’s partId:

curl -X 'GET' \
    'https://cad.onshape.com/api/v9/parts/d/{sourceDid}/w/{sourceWid}/e/{sourceEid}?withThumbnails=false&includePropertyDefaults=false' \
    -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'

Locate the partId for "name": "CRANKSHAFT" in the response body:

[{
    "name": "CRANKSHAFT",
    "state": "IN_PROGRESS",
    "description": "Crankshaft",
    "revision": null,
    "partNumber": "PRT-10230",
    "elementId": "{sourceEid}",
    "partId": "JJH",
    "bodyType": "solid",
    "microversionId": "{sourceMid}",
    "customProperties": {
    "57f3fb8efa3416c06701d61e": "false"
    },
    ...
}]

Now open the myNewAssembly tab you created in the last tutorial. We’ll insert our part into this assembly. Make a note of the following from the URL:
- documentId - we’ll refer to this as our targetDid
- workspaceId - this is our targetWid
- elementId of the assembly - this is our targetEid

Call the createInstance endpoint on the assembly to insert an instance of the part into the assembly. Make sure to replace the IDs in the request URL match those from your copied target document.

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 '{
        "documentId": "{sourceDid}",
        "elementId": "{sourceEid}",
        "includePartTypes": [
            "PARTS"
        ],
        "partId": "{partId}"
        }'

Note: you can add "versionId": "{sourceVid}" to the request body if needed.

Refresh your assembly and confirm the part has been added.
Repeat steps 4-7 to add the FLYWHEEL part from the CRANK Part Studio to the myNewAssembly assembly.

Get assembly definition

Follow all steps in the Insert a part into an assembly tutorial.
Open the myNewAssembly tab in your copied document make a note of the document, workspace, and element (tab) IDs in the URL.

Call the getAssemblyDefinition/ endpoint:

curl -X 'GET' \
    'https://cad.onshape.com/api/v9/assemblies/d/{did}/{wvm}/{wvmid}/e/{eid}' \
    -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'

The assembly definition information is returned in JSON format in the response body.
- Make a note of the rootAssembly.instances.id for "name": "CRANKSHAFT <1>"; we’ll use this instanceId to modify the assembly in the Modify an assembly tutorial.
- Make a note of the rootAssembly.instances.id for "name": "FLYWHEEL <1>"; we’ll use this as our nodeId in the Delete an assembly instance tutorial.
```
   "instances": [{
    "isStandardContent": false,
    "type": "Part",
    "name": "CRANKSHAFT <1>",
    "suppressed": false,
    "id": "{instanceId}",
    "partId": "{partId}",
    "fullConfiguration": "default",
    "configuration": "default",
    "documentId": "{did}",
    "elementId": "{eid}",
    "documentMicroversion": "{mid}"
  },
    ...
  ]
```

Modify an assembly

Follow all steps in the Get assembly definition tutorial.

Call the modify endpoint on your myNewAssembly tab. Send the desired modification information in the request body. In this example, we’ll use the modify endpoint to delete the CRANKSHAFT instance from the assembly.

curl -X 'POST' \
    'https://cad.onshape.com/api/v9/assemblies/d/{did}/w/{wid}/e/{eid}/modify' \
    -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 ' {
            "deleteInstances": [{instanceId}]
        }

Refresh your document and observe that the instance has been deleted from the assembly.

Delete an assembly instance

You can also use the deleteInstance endpoint to remove instances from an assembly.

Follow all steps in the Modify an assembly tutorial.

Call the deleteInstance endpoint to delete the FLYWHEEL instance from the assembly. Use the instanceId from the Get assembly definition tutorial from the last step as the nodeId ({nid}) in the URL.

curl -X 'POST' \
    'https://cad.onshape.com/api/v9/assemblies/d/{did}/w/{wid}/e/{eid}/instance/nodeid/{nid}' \
    -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'

Return to your Onshape document and confirm the instance has been removed from the assembly.