Assemblies

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

📘 Notes

  • This page provides sample code as curls. See the curl documentation for more information.
  • All Onshape API calls must be properly authenticated by replacing the CREDENTIALS variable in the curls below. 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.
  • This documentation refers to Onshape IDs in the following format: {did}, {wvmid}, {eid}, {pid}, {otherId}. These represent document, workspace (or version or microversion), element, part, and other IDs (respectively) that are needed make the API calls. We sometimes abbreviate these variables as DWVEM Please see API Guide: API Intro for information on what these IDs mean and how to obtain them from your documents. Never include the curly braces ({}) in your API calls.
  • For Enterprise accounts, replace cad in all Onshape URLs with your company domain. https://cad.onshape.com > https://companyName .onshape.com
  • 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

  1. Make a copy of this public document, and make a note of the copied document and workspace IDs in the URL.
  2. 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"
    }'
  3. Return to your document and observe that the new assembly tab has been added.
    new assembly tab in the copied api guide document

Insert a part into an assembly

  1. Follow all steps in the Create an assembly tutorial.
  2. 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
      crank part studio tab in the copied api guide document

  3. 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'
  4. 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"
    },
    ...
}]
  5. 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
  6. 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.
  7. Refresh your assembly and confirm the part has been added.
    new assembly tab showing the crankshaft part instance

  8. Repeat steps 4-7 to add the FLYWHEEL part from the CRANK Part Studio to the myNewAssembly assembly.
    new assembly tab showing both the crankshaft and flywheel part instances

Get assembly definition

  1. Follow all steps in the Insert a part into an assembly tutorial.
  2. Open the myNewAssembly tab in your copied document make a note of the document, workspace, and element (tab) IDs in the URL.
  3. 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'
  4. 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

  1. Follow all steps in the Get assembly definition tutorial.
  2. Call the modify endpoint on your myNewAssembly tab. Send the desired modifcation 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}]
        }
  3. Refresh your document and observe that the instance has been deleted from the assembly.
    crankshaft instance has been removed from the new assembly

Delete an assembly instance

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

  1. Follow all steps in the Modify an assembly tutorial.
  2. 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'
  3. Return to your Onshape document and confirm the instance has been removed from the assembly.
    new assembly tab in the copied api guide document

Additional Resources