Configurations

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

You can use Configurations to create variations of entire Part Studios, Assemblies, specific parts and more. You can configure feature and parameter values, part properties, custom part properties, face and part appearances, and sketch text. Each Part Studio can have only one Configuration, but it can contain multiple Configuration inputs. The Configuration inputs you define for a Part Studio become options when inserting that Part Studio into an Assembly or Drawing. You can also create your own Configurations for an Assembly, regardless of any existing Part Studio Configurations. Assembly Configurations work the same way as Part Studio Configurations, but are limited to configuring Mates (not Mate connectors), instances, and patterns.

📘 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}, {wid}, {eid}, {pid}, {otherId}. These represent document, workspace, 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

Endpoints

Element/getConfiguration: Get the configuration data for a Part Studio or Assembly.

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'

Element/updateConfiguration: Update the configuration data for a Part Studio or Assembly.

curl -X 'POST' \
    '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' \
    -d '{ }'

Element/decodeConfiguration: Process an encoded configuration file.

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

Element/encodeConfigurationMap: Create an encoded map of configurations.

curl -X 'POST' \
    'https://cad.onshape.com/api/v6/elements/d/{did}/e/{eid}/configurationencodings' \
    -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 '{
        "parameters": [
        {
            "parameterId": "{parameterId}",
            "parameterValue": "{configValue}"
        }
        ]
    }'

Encoded Configuration Strings

The Element/encodeConfigurationMap and Element/decodeConfiguration APIs convert parameters from JSON to a URL-encoded string in the following format: "configuration=parameterId%3DparameterValue"

For example,

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

encodes to:

"configuration=List_izOjbm5HCRXEld%3D_500_mm"

and:

"configuration=List_izOjbm5HCRXEld%3DDefault"

decodes to:

{
    "parameters": [
        {
        "parameterId": "List_izOjbm5HCRXEld",
        "parameterValue": "Default"
        }
    ]
}

Sample Workflows

These sample workflows all build off one another. Completing all of the workflows will take you step-by-step through the process of getting Configuration information, encoding the information for use, and using the encoded configuration to create a configured export. You can also watch the video to see the entire workflow in the Glassworks API Explorer.

Get a Configuration

In this example, we’ll use the Element/getConfiguration endpoint to get the Configuration information from a Part Studio.

Make a copy of this public document. Make a note of the new document’s document ID, workspace ID, and element ID.
Click the Configurations dropdown in the Features list, and observe that there are two options for the drillbit length, 250 mm and 500 mm.
Set up a call to the Element/getConfiguration endpoint to get the Configuration for the Part Studio. Don’t forget to replace the URL parameters with the IDs from your copy of the document, and replace CREDENTIALS with your authorization credentials.
```
curl -X 'GET' \
    'https://cad.onshape.com/api/v6/elements/d/{did}/w/{wid}/e/{eid}/configuration' \
    -H 'Accept: application/json;charset=UTF-8; qs=0.09' \
    -H 'Authorization: Basic CREDENTIALS' \
```

Review the Configuration information detailed in the response. You can see that the Part Studio contains one configuration (Drill_Bit_Length) with two options (250 mm and 500 mm):

{
    "btType": "BTConfigurationResponse-2019",
    "currentConfiguration": [
        {
            "btType": "BTMParameterEnum-145",
            "namespace": "",
            "nodeId": "{nodeId1}",
            "value": "Default",
            "enumName": "{paramId_conf}",
            "parameterId": "{paramId}"
        }
    ],
    "configurationParameters": [
        {
            "btType": "BTMConfigurationParameterEnum-105",
            "defaultValue": "Default",
            "enumName": "{enumName}",
            "namespace": "",
            "options": [
                {
                    "btType": "BTMEnumOption-592",
                    "optionName": "250 mm",
                    "option": "Default",
                    "nodeId": "{nodeId2}"
                },
                {
                    "btType": "BTMEnumOption-592",
                    "optionName": "500 mm",
                    "option": "_500_mm",
                    "nodeId": "{nodeId3}"
                }
            ],
            "isCosmetic": false,
            "parameterId": "{paramId}",
            "parameterName": "Drill_Bit_Length",
            "nodeId": "{nodeId4}"
        }
    ],
    "serializationVersion": "1.2.0",
    "sourceMicroversion": "{mid}",
    "microversionSkew": false,
    "rejectMicroversionSkew": false,
    "libraryVersion": 2296
}

Encode a configuration string

In this example, we’ll encode a Configuration so it can be used as part of a translation (i.e., an export). Please read the Encoded Configuration Strings section before beginning this example.

This example builds off the previous one. Please complete the Get a Part Studio Configuration workflow to obtain the raw Configuration output for the Part Studio.

Set up a call to the Element/encodeConfigurationMap endpoint. Don’t forget to replace the URL parameters with the IDs from your document, and replace CREDENTIALS with your authorization credentials.

curl -X 'POST' \
    'https://cad.onshape.com/api/v6/elements/d/{did}/e/{eid}/configurationencodings' \
    -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 '{ }'

Now we need to create our JSON body for the request. Note the structure of the body:
```
{
"parameters": [
    {
    "parameterId": "string",
    "parameterValue": "string"
    }
],
"standardContentParametersId": "string"
}
```
Fill out the request body with our information:
- We’re not using a standard content part, so we can delete the second key/value pair.
- The parameterId can be found in the response from the previous example. It usually begins with (List_)
- For the parameter value, we’ll enter one of our configuration options from the previous example. In this case, we’ll use _500_mm to export a 500 mm drillbit part.
```
{
"parameters": [
    {
    "parameterId": "{parameterId}",
    "parameterValue": "_500_mm"
    }
]
}
```

Now we can make our call:

curl -X 'POST' \
   'https://cad.onshape.com/api/v6/elements/d/{did}/e/{eid}/configurationencodings' \
   -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 '{
        "parameters": [
       {
           "parameterId": "{parameterId}",
           "parameterValue": "_500_mm"
       }
       ]
   }'

The call responds with two values: the ID of the encoding, and the encoded configuration string. We can use this configuration string (returned in the queryParam field) any time we want to specify the 500 mm drillbit length.
```
{
    "encodedId": "{encodedId}",
    "queryParam": "configuration={configString}"
}
```

Export a configured part

In this example, we will export a configured part. We have a drillbit with two configurations: 250 mm and 500 mm lengths. To export a 500 mm drillbit, we can specify the configuration as part of the export.

This example builds off the previous two. Please complete this exercise after the Encode a configuration workflow.
Next, set up a call to the PartStudio/exportParasolid endpoint. Don’t forget to replace the URL parameters with the IDs from your document, and replace CREDENTIALS with your authorization credentials. Note that this endpoint includes an optional configuration parameter. This is where we’ll enter the configuration string we found in the previous example.
```
curl -X 'GET' \
    'https://cad.onshape.com/api/v6/partstudios/d/{did}/w/{wid}/e/{eid}/parasolid?version=0&includeExportIds=false&configuration={configString}&binaryExport=false' \
    -H 'Accept: */*' \
    -H 'Authorization: Basic CREDENTIALS' \
```

This endpoint returns a redirect URL. Navigate to the returned URL in your browser to download the export.

Hint: The URL will look something like this, but with different IDs:

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

Now we need to import our Parasolid to confirm the correct configuration was used. Open your document in the Onshape UI, click the Insert new tab button, and then select Import.
Navigate to the export you downloaded (with the .x_t extension) and import it into Onshape.
Use the measure tool to confirm the length of the imported drillbit is 500 mm.

Workflow Video

This video demonstrates how to complete the above tutorials in the Onshape API Explorer.