Assemblies

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

ℹ️ Onshape API Notes
  • All Onshape API calls must be properly authenticated.
  • For Enterprise accounts, replace cad in URLs with your company domain.
  • Onshape IDs are written as: {did}, {wvmid}, {eid}, {pid}, {otherId}. See Onshape API Intro for information on what these IDs mean and how to obtain them from your documents.
  • Variables for replacement are written as: {variable1} or <variableTwo>. Never include the braces or angle brackets themselves with these variables.
  • Visit the Learning Center's Intro to the Onshape API course for additional instruction and videos.

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'

Assembly transforms

See Sample Workflows: Transform an assembly for a working example.

ℹ️ NOTES

  • Onshape assemblies use object-to-world affine transforms.
  • Unlike in graphics or robotics, occurrence transforms are absolute and not relative to their parent's transform.
  • Transforms are defined with regard to the top-level assembly's coordinate-system, which is determined by the source Part Studio where the instance was modeled.
    • A part occurrence transform represents the location of the owning Part Studio's coordinate system relative to the top-level assembly's coordinate system.
    • Transforms are defined the same way for rigid sub-assemblies.
  • Each transform is encoded as a 4x4 matrix.

Matrices are encoded as:

| R00  R01  R02  Tx |
| R10  R11  R12  Ty |
| R20  R21  R22  Tz |
|  0    0    0    1 |

Where:

  • Rij encodes rotation
  • Txyz encodes translation
  • The last row is always 0,0,0,1

When working with subassembly instances, transformations in each level are independent. When you call the getAssemblyDefinition endpoint, each part and subassembly is returned in the occurrences array. Each occurrence includes a transform matrix, which represents the absolute location of the occurrence in the top-level assembly’s coordinate system. The part occurrence’s coordinate system is the coordinate system of the Part Studio.

For example:

  1. Insert Part 1 into Assembly 1.
  2. In Assembly 1, move the part instance 30 mm along the X-axis.
  3. Call the getAssemblyDefinition endpoint on Assembly 1. The transform matrix displays the 30 mm (0.03 meter) transform.
    {
  "occurrences": [
  {
    "transform": [
      1,0,0,0.03,
      0,1,0,0,
      0,0,1,0,
      0,0,0,1
    ]
  }]
}
  4. Insert Assembly 1 into Assembly 2.
  5. In Assembly 2, move the part instance 50 mm along the X-axis.
  6. Call the getAssemblyDefinition endpoint on Assembly 2. The transform matrix indicates that the part has been moved a total of 80 mm (0.08 meter) from the source in the Part Studio.
    {
  "occurrences": [
    {
      "transform": [
        1,0,0,0,
        0,1,0,0,
        0,0,1,0,
        0,0,0,1
      ]
    },
    {
      "transform": [
        1,0,0,0.08,
        0,1,0,0,
        0,0,1,0,
        0,0,0,1
      ]
    }
  ]
}
subassembly transformation in Onshape

When instances are mated in an assembly, transformations done in the Part Studio can affect the transform result from the getAssemblyDefinition endpoint. For example, if you rotate a rectangular box in the Part Studio, the instances of the box in the assembly automatically rotate as well, but the getAssemblyDefinition remains unchanged, because the assembly has not been transformed away from the origin Part Studio.

part transformation in a part studio

mate forces part instances into new positions

{
  "occurrences": [
    {
    "transform": [
        1,0,0,0.04152549794188961,
        0,1,0,0.025139995726138297,
        0,0,1,-0.0021900598728476495,
        0,0,0,1
    ]},
    {
    "transform": [
        1,0,0,0,
        0,1,0,0,
        0,0,1,0,
        0,0,0,1
    ]}
  ]
}

To apply a transformation via the API, see Sample Workflows: Transform an assembly

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

Create a mate connector in an assembly

Given an assembly that includes at least one part, use the following code to create a mate connector on the part.

Notes:

  • The btType for creating a mate is BTMMateConnector-66.
  • Call getAssemblyDefinition to obtain the instanceId and partId of the part(s) on which to place the mate connector.
    • When referencing a part in a subassembly, form a chain of instanceIds starting from the top-level instance down to the instance that should own the mate connector. Call getAssemblyDefinition on each subassembly to get the next instanceId.
  • Use the partId to call getBodyDetails to get the id of the part face(s), edge(s), or vertex(es) on which to place the mate connector; use this as the deterministicId.
  • To join mate connectors, create a mate.
  • This example shows creating 3 mate connectors.

Endpoint

POST /api/v12/assemblies/d/{did}/{wvm}/{wvmid}/e/{eid}/features

Request Body

{
  "feature": {
      "btType": "BTMMateConnector-66",
      "featureType": "mateConnector",
      "name": "Mate connector 1",
      "parameters": [
        {
          "btType": "BTMParameterEnum-145",
          "enumName": "Origin type",
          "value": "ON_ENTITY",
          "parameterId": "originType"
        },
        {
          "btType": "BTMParameterQueryWithOccurrenceList-67",
          "queries": [
            {
              "btType": "BTMInferenceQueryWithOccurrence-1083",
              "inferenceType": "CENTROID",
              "path": [
                <instanceIdOne>,
                <instanceIdTwo>,
                <instanceIdThree>
              ],
              "deterministicIds": [
                <deterministicIdOne>,
                <deterministicIdTwo>,
                <deterministicIdThree>
              ]
            }
          ],
          "parameterId": "originQuery",
          "parameterName": "",
          "libraryRelationType": "NONE"
        }
      ],
      "isHidden": false,
      "suppressed": false
    }
}

Create a mate in an assembly

Given an assembly that includes two mate connectors, use the following code to create a Fastened mate between them.

  • Use the featureId returned when creating the mate connector, or call Assembly/getFeatures to obtain the featureId of the mate connectors to join.
  • The btType for creating a mate is BTMMate-64 and supports the following types (sent in the parameters.value field):
    FASTENED
SLIDER
CYLINDRICAL
REVOLUTE
PIN_SLOT
PLANAR
BALL
PARALLEL

Endpoint

POST /api/v12/assemblies/d/{did}/{wvm}/{wvmid}/e/{eid}/features

Request Body

{
  "feature": {
      "btType": "BTMMate-64",
      "featureType": "mate",
      "returnAfterSubfeatures": false,
      "subFeatures": [],
      "namespace": "",
      "version": 2,
      "name": "Fastened 1",
      "parameters": [
        {
          "btType": "BTMParameterEnum-145",
          "namespace": "",
          "enumName": "Mate type",
          "value": "FASTENED",
          "parameterId": "mateType"
        },
        {
          "btType": "BTMParameterQueryWithOccurrenceList-67",
          "queries": [
            {
              "btType": "BTMFeatureQueryWithOccurrence-157",
              "path": [],
              "featureId": <featureIdOne>,
              "queryData": ""
            },
            {
              "btType": "BTMFeatureQueryWithOccurrence-157",
              "path": [],
              "featureId": <featureIdTwo>,
              "queryData": ""
            }
          ],
          "parameterId": "mateConnectorsQuery"
        }
      ],
      "suppressed": false
    }
}

Transform an assembly

To create a transformation via the API, add the encoded transform matrix to the transformDefinitions array in the modify request body.

  • See Assembly transforms for details on encoding the transform matrix.
  • Call the Get assembly definition endpoint to obtain the path to the assembly or subassembly.
    • The path is an array of strings that map the top-level assembly path down to the occurrence you want to transform.
    • Each path string usually takes a form similar to M4QG1rVZfozeARX+H.

This example translates a second-level subassembly (indicated by the two IDs provided in the path) by 1.3 m along the X-axis:

Endpoint

POST assemblies/did/{did}/w/{wid}/e/{eid}/modify

Request Body

{
  "transformDefinitions": [
    {
      "occurrences": [
        {
          "path": [
            <topLevelPath>,
            <secondLevelPath>
          ]
        }
      ],
      "transform": [
        1,0,0,1.3,
        0,1,0,0,
        0,0,1,0,
        0,0,0,1
      ]
    }
  ]
}

Suppress and unsuppress an instance

Suppress or unsuppress an instance in an assembly. To suppress assembly instances with configurations, see Configure suppression of an instance.

Endpoint

POST assemblies/did/{did}/w/{wid}/e/{eid}/modify

Request Body

{
  "suppressionStates": {
    "additionalProp1": { // ID of instance to unsuppress
      "value": "false"
    },
    "additionalProp2": { // ID of instance to suppress
      "value": "true"
    }
  }
}

Notes

Example

  1. Create two simple parts in Onshape and insert them into an assembly.
  2. Right click Part 1, and select Suppress.

    assembly with one part suppressed and one unsuppressed

  3. Call the getAssemblyDefinition endpoint and make a note of the instance ID for each part:
    {
  "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
}
  4. Use the instance IDs from the previous step to call the assembly modify endpoint with the request body below. This unsuppresses Part 1 and suppresses Part 2:
    {
  "suppressionStates": {
    "instanceIdPartOne": {
      "value": "false"
    },
    "instanceIdPartTwo": {
      "value": "true"
    }
  }
}
  5. Call the getAssemblyDefinition endpoint again or view the assembly in Onshape to confirm the parts’ suppression has been swapped:

    assembly with part suppression reversed

Configure suppression of an instance

You can modify suppression of assembly instances via configuration. To suppress assembly instances without configurations, see Suppress and unsuppress an instance.

Endpoint

POST assemblies/did/{did}/w/{wid}/e/{eid}/modify

Request Body

{
  "suppressionStates": {
    "additionalProp1": // ID of assembly instance being configured
    { 
      "configuredValue": {
        "configurationParameterId": "configParameterId", // configuration ID
        "configurationToValue": {
          "additionalProp1": "false", // suppression for Default configuration; usually `"Default"`
          "additionalProp2": "true" // suppression for additional config option(s)
        }
      }
    }
  }
}

Notes

Example

  1. Set up the suppression configuration shown in the image below. By default, both parts are unsuppressed (visible). This example sets the Part 2 suppression to true when the Option 1 configuration is selected.

    assembly configuration panel showing two options, both with the Unsuppressed option selected

  2. Call the getAssemblyDefinition endpoint to get the instance ID of the part to configure (Part 2):
    {
    "rootAssembly": {
        // json truncated
        "instances": [
        {
            "isStandardContent": false,
            "type": "Part",
            "id": "instanceIdPartOne",
            "name": "Part 1 <1>",
            "suppressed": false,
            "partId": "JHD",
            "fullConfiguration": "default",
            "configuration": "default",
            "documentId": "did",
            "elementId": "eid",
            "documentMicroversion": "mid"
        },
        {
            "isStandardContent": false,
            "type": "Part",
            "id": "instanceIdPartTwo", // Copy this ID; assembly instance being configured
            "name": "Part 2 <1>",
            "suppressed": false, // Part 2 is not suppressed
            "partId": "JHH",
            "fullConfiguration": "default",
            "configuration": "default",
            "documentId": "did",
            "elementId": "eid",
            "documentMicroversion": "mid"
        }
        ],
        "fullConfiguration": "configId=Default",
        "configuration": "default",
        "documentId": "did",
        "elementId": "eid",
        "documentMicroversion": "mid"
    }
    // json truncated
}
  3. Call the getConfiguration endpoint on the assembly to get the node ID of the configuration option value to set:
    {
"btType": "BTConfigurationResponse-2019",
"rejectMicroversionSkew": false,
"microversionSkew": false,
"currentConfiguration": [],
"configurationParameters": [
    {
    "btType": "BTMConfigurationParameterEnum-105",
    "parameterId": "configParameterId",  // Copy this ID ; configuration parameter to modify
    "enumName": "configIf_conf",
    "enumOptionVisibilityConditions": {
        "btType": "BTEnumOptionVisibilityConditionList-2936",
        "visibilityConditions": []
    },
    "isCosmetic": false,
    "defaultValue": "Default",
    "options": [
        {
        "btType": "BTMEnumOption-592",
        "optionName": "Default",
        "option": "Default", // Copy this string; Default config option
        "nodeId": "nodeIdDefault"
        },
        {
        "btType": "BTMEnumOption-592",
        "optionName": "Option 1",
        "option": "Option_1", // Copy this string; "Option 1" config option
        "nodeId": "nodeIdOption1"
        }
    ],
    "namespace": "",
    "nodeId": "configNodeId",
    "parameterName": "Configuration",
    "visibilityCondition": {
        "btType": "BTParameterVisibilityCondition-177"
    }
    }
],
"serializationVersion": "1.2.19",
"sourceMicroversion": "{mid}",
"libraryVersion": 2960
}
  4. Use the IDs to call the assembly modify endpoint with the following request body. This changes the suppression of the instance (Part 2) to true when the Option 1 configuration is selected:
    {
  "suppressionStates": {
    "instanceIdPartTwo": {
      "configuredValue": {
        "configurationParameterId": "configParamId",
        "configurationToValue": {
            "Default": "false",
            "Option_1": "true"
        }
      }
    }
  }
}
  5. Call the getAssemblyDefinition endpoint again or view the assembly in Onshape to confirm that Part 2 is suppressed in the Option 1 configuration:

    assembly instance suppressed via config

Additional Resources