Features

This page describes the APIs Onshape provides for creating and manipulating features and the Feature List in a Part Studio.

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

FeatureScript vs REST API

When working with complex geometry, you might find working directly in FeatureScript easier than working with the Onshape REST API. Click here to see the FeatureScript documentation.

Endpoints

The following endpoints are available for working with features and the Feature List:

  • Get the Feature List
    curl -X 'GET' \
  'https://cad.onshape.com/api/v6/partstudios/d/{did}/{wvm}/{wvmid}/e/{eid}/features?rollbackBarIndex=-1&includeGeometryIds=true&noSketchGeometry=false' \
  -H 'accept: application/json;charset=UTF-8; qs=0.09' \
  -H 'Authorization: Basic CREDENTIALS'
  • Add a Feature
    curl -X 'POST' \
  'https://cad.onshape.com/api/v6/partstudios/d/{did}{wvm}/{wvmid}/e/{wid}/features' \
  -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 '{
      "btType": "BTFeatureDefinitionCall-1406",
      "feature": {
        "btType": "BTMFeature-134",
        "featureType": "",
        "name": "",
        "parameters": []
      }
    }'
  • Update a Feature
      curl -X 'POST' \
    'https://cad.onshape.com/api/v6/partstudios/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' \
    -d '{
        "btType": "BTFeatureDefinitionCall-1406",
        "feature": {
          "btType": "BTMFeature-134",
          "featureId": "{fid}",
          "parameters": []
        }
      }'
  • Update Multiple Features
      curl -X 'POST' \
    'https://cad.onshape.com/api/v6/partstudios/d/{did}/w/{wid}/e/{eid}/features/updates' \
    -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 '{
        "btType": "BTUpdateFeaturesCall-1748",
        "features": [
          {
          "btType": "BTMFeature-134",
          "featureId": "{fid1}",
          "parameters": []
          },
          {
          "btType": "BTMFeature-134",
          "featureId": "{fid2}",
          "parameters": []
          }
        ]
      }'
  • Delete a Feature
    curl -X 'DELETE' \
  'https://cad.onshape.com/api/v6/partstudios/d/{did}/{wvm}/{wvmid}/e/{eid}/features/featureid/{fid}' \
  -H 'accept: application/json;charset=UTF-8; qs=0.09' \
  -H 'Authorization: Basic CREDENTIALS'

JSON encoding

Instead of providing a translation layer between a feature’s internal and external formats, these APIs present the internal format of the feature definitions to the user. The best way to familiarize yourself with the formats involved is by calling the Get the Feature List endpoint on existing Part Studios.

📘 Notes

  • Onshape REST API parameters may change at any time. The documentation on this page is accurate for v6 of the Onshape API. The quickest way to verify what parameters are needed for a call is to create the sketch/feature in the Onshape UI, then call the Get the Feature List API and see what parameters are returned for the feature.

📘 Notes

  • Default values are sometimes omitted in the encoded output. These defaults are:
    • String: ""
    • Boolean: false
    • Numeric: 0
  • The JSON encoding uses a special tagging system to manage polymorphic data structures. Objects are generally by enclosing them within another object that declares the type information for the enclosed object.

Feature types

Below, find the available types for working with features in the API.

  • BTMFeature-134 - General feature type
  • BTMSketch-151 - Feature type for sketches

Parameter types

All parameters have the following fields in common:

  • parameterId - Unique ID of the parameter
  • nodeId - Unique ID of the parameter node

The parameter types available for use in the API are:

  • BTMParameterQuantity-147
    • expression - Define the value for the parameter
  • BTMParameterQueryList-148 - defined by one of the following:
    • SBTMIndividualQuery-138
      • geometryIds - List of geometry IDs the feature applies to
    • SBTMIndividualSketchRegionQuery-140
      • featureId - Feature ID of the sketch for which to include all regions
  • BTMParameterBoolean-144
    • value - true | false
  • BTMParameterEnum-145
    • enumName - Name of the enum type that the value is a member of
    • value - The enum member

Sketch plane IDs

The following string can be sent along with the PartStudios/featurescript API to get the plane ID. You can then use that ID to specify the plane on which to create a sketch.

function(context is Context, queries) { 
  return transientQueriesToStrings(evaluateQuery(context, qCreatedBy(makeId(\"{planeName}\"), EntityType.FACE))); 
}

For example, to get the ID of the Top plane, you would make the following call:

curl -X 'POST' \
  'https://demo-c.dev.onshape.com/api/v6/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))); }"
}'

Sample Workflows

Below are several examples of how the API can be used in order to help you get started. The calls could be executed using your preferred software environment but interactive use in a REST-aware tool is likely the easiest way to try the examples.

Get the list of features in a Part Studio

One of the best ways to familiarize yourself with the Onshape Feature APIs is to view the API details for existing features in a Part Studio. In this example, we’ll add three features to a Part Studio, and then call the PartStudio/getPartStudioFeatures API on the Part Studio. We’ll then be able to view the structure of the way features are represented in the API.

  1. Create a new document or open an existing one.
  2. Create a new sketch in the document, and draw a long rectangle.
  3. Extrude the rectangle.
  4. Add a fillet to one edge of the part.
  5. Call the PartStudio/getPartStudioFeatures API. Replace the URL parameters with the values from your document, and replace CREDENTIALS with your authorization credentials.
    curl -X 'GET \
  'https://cad.onshape.com/api/v6/partstudios/d/{did}/{wvm}/{wvmid}/e/{eid}/features?rollbackBarIndex=-1&includeGeometryIds=true&noSketchGeometry=false' \
  -H 'Authorization: Basic CREDENTIALS' \
  -H 'Accept: application/json;charset=UTF-8; qs=0.09'
  6. Review the JSON returned in the response body. A lot of information is returned, but it will look something like the truncated snippet below. Notice that there are objects returned for each feature in the Part Studio– the sketch, the extrude, the fillet, and the chamfer. Each default plane and the origin in the Part Studio also appear in the defaultFeatures object. The Standard Geometry library is listed as an import, and the response also includes the state of each feature. :
    {
    "btType": "BTFeatureListResponse-2457",
    "isComplete": true,
    "serializationVersion": "1.2.4",
    "rollbackIndex": 4,
    "features": [
      {
        "btType": "BTMSketch-151",
        "entities": [...],
        "constraints": [...],
        "name": "Sketch 1",
        "suppressed": false,
        "parameters": [...],
        "featureId": "{fid1}",
        "featureType": "newSketch",
        "subFeatures": [...],
        "returnAfterSubfeatures": false
      },
      {
        "btType": "BTMFeature-134",
        "name": "Extrude 1",
        "suppressed": false,
        "parameters": [...]
        "featureId": "{fid2}",
        "featureType": "extrude",
        "subFeatures": [],
        "returnAfterSubfeatures": false
      },
      {
        "btType": "BTMFeature-134",
        "name": "Fillet 1",
        "suppressed": false,
        "parameters": [...],
        "featureId": "{fid3}",
        "featureType": "fillet",
        "subFeatures": [...],
        "returnAfterSubfeatures": false
      },
      {
        "btType": "BTMFeature-134",
        "name": "Chamfer 1",
        "suppressed": false,
        "parameters": [...],
        "featureId": "{fid4}",
      }
    ],
    "featureStates": {
      "{fid1}": {
        "btType": "BTFeatureState-1688",
        "featureStatus": "OK",
        "inactive": false
      },
      ...
    },
    "defaultFeatures": [
      {
        "btType": "BTMFeature-134",
        "name": "Origin",
      },
      {
        "btType": "BTMFeature-134",
        "name": "Top",
      },
      {
        "btType": "BTMFeature-134",
        "name": "Front",
      },
      {
        "btType": "BTMFeature-134",
        "name": "Right",
      }
    ],
    "imports": [
      {
        "btType": "BTMImport-136",
        "path": "onshape/std/geometry.fs",
        "version": "2232.0"
      }
    ],
    "libraryVersion": 2232
  }

Create a cube feature

In this example we will create a cube using the cube feature. The feature accepts a single parameter (the length of a side) and creates a cube with a corner at the origin and aligned with the three default planes.

  1. Create a new document or open an existing one. We’ll create the cube feature in this document.
  2. Begin to create the PartStudio/addPartStudioFeature call. Replace the URL parameters with the values from your document, and replace CREDENTIALS with your authorization credentials. This is a call to the same endpoint as in the previous example, but is a POST instead of a GET.
    curl -X 'POST \
  'https://cad.onshape.com/api/v6/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>
      }'
  3. Add the following as the JSON body.
    • Note the btType defines this as a Feature.
    • We’ve named the feature cube and inserted an instance of the feature named Cube 1 into the Part Studio.
    • The cube feature has one parameter– the cube sideLength in inches, which is set to 1 by default.
    {
  "btType": "BTFeatureDefinitionCall-1406",
  "feature": {
    "btType": "BTMFeature-134",
    "featureType": "cube",
    "name": "Cube 1",
    "parameters": [
      {
          "btType": "BTMParameterQuantity-147",
          "isInteger": false,
          "expression": "1 in",
          "parameterId": "sideLength"
        }
    ],
    "returnAfterSubfeatures": false,
    "suppressed": false
  }
}
  4. Confirm your call matches the following, and then make the call:
    curl -X 'POST \
  'https://cad.onshape.com/api/v6/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 '{
      "btType": "BTFeatureDefinitionCall-1406",
      "feature": {
        "btType": "BTMFeature-134",
        "featureType": "cube",
        "name": "Cube 1",
        "parameters": [
          {
              "btType": "BTMParameterQuantity-147",
              "isInteger": false,
              "expression": "1 in",
              "parameterId": "sideLength"
            }
        ],
        "returnAfterSubfeatures": false,
        "suppressed": false
      }
    }'
  5. Return to your console to review the endpoint response. The output returns:
    • The feature definition that we provided as input with nodeIds and a featureId. Make a note of the featureId; we’ll use it in the next example.
    • Information that the feature executed correctly
    • The serialization version and microversion of the document that resulted from the feature addition
      {
  "btType": "BTFeatureDefinitionResponse-1617",
  "featureState": {
    "btType": "BTFeatureState-1688",
    "featureStatus": "OK",
    "inactive": false
  },
  "feature": {
    "btType": "BTMFeature-134",
    "name": "Cube 1",
    "suppressed": false,
    "parameters": [
      {
        "btType": "BTMParameterQuantity-147",
        "value": 0,
        "units": "",
        "isInteger": false,
        "expression": "1 in",
        "nodeId": "{nid1}",
        "parameterId": "sideLength"
      }
    ],
    "featureId": "{fid}",
    "nodeId": "{nid2}",
    "featureType": "cube",
    "returnAfterSubfeatures": false,
    "subFeatures": [],
    "namespace": ""
  },
  "serializationVersion": "1.2.4",
  "sourceMicroversion": "{mid}",
  "microversionSkew": false,
  "rejectMicroversionSkew": false,
  "libraryVersion": 0
}
  6. Open your document and confirm that the cube has been inserted into the Part Studio.
    cube added to part studio via features api
  7. Double-click Cube 1 in the Feature List to open the Cube 1 dialog. Change the sideLength to 3 and click the checkbox. Note that the size of the cube changes automatically.
    cube parameter updated to 3 inches

Create a sketch

In this example, we’ll create a circular sketch feature with the following properties:

  • While other features use a btType of BTMFeature-141, sketches have their own special type: BTMSketch-151
  • Sketches must use the newSketch featureType
  • Sketch plane ID: Front
  • Radius: 0.025 inches
  • Location: (0.05, 0.05)
  1. Open a new PartStudio. Note the following:
    • Document ID
    • Workspace ID
    • Element ID (of the Part Studio tab)
  2. We want to create the circle on the Front plane, so we’ll call the PartStudios/featurescript endpoint to get its ID:
    curl -X 'POST' \
  'https://demo-c.dev.onshape.com/api/v6/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(\"Front\"), EntityType.FACE))); }"
}'
    The call returns the following, identifying the plane as JCC.
    {
  "btType": "BTFeatureScriptEvalResponse-1859",
  "result": {
    "btType": "com.belmonttech.serialize.fsvalue.BTFSValueArray",
    "value": [
      {
        "btType": "com.belmonttech.serialize.fsvalue.BTFSValueString",
        "value": "JCC",
        "typeTag": ""
      }
    ],
    "typeTag": ""
  }
}
  3. Now we’ll create the JSON structure for our sketch. All sketches must be created with the BTMSketch-151 btType and the newSketch featureType. Note how we’ve specified the plane to use in the sketchPlane parameter, and the geometry details.
    {
  "feature" : {
    "btType": "BTMSketch-151", 
    "featureType": "newSketch", 
    "name": "Sketch 1", 
    "parameters": [
      {
        "btType": "BTMParameterQueryList-148",
        "queries": [
          {
            "btType": "BTMIndividualQuery-138",
            "deterministicIds": [ "JCC" ] 
          }
        ],
        "parameterId": "sketchPlane" 
      }
    ],
    "entities": [
      {
        "btType": "BTMSketchCurve-4",
        "geometry": {
          "btType": "BTCurveGeometryCircle-115",
          "radius": 0.025,  
          "xcenter": 0.05,
          "ycenter": 0.05,  
          "xdir": 1,
          "ydir": 0, 
          "clockwise": false 
        },
        "centerId": "circle-entity.center",
        "entityId": "circle-entity"
      }  
    ],
    "constraints": [      
    ]
  }
}
  4. Now we’ll add the JSON structure to our code and call the endpoint. Replace the URL parameters with the values from your document, and replace CREDENTIALS with your authorization credentials.
    curl -X 'POST' \
  'https://cad.onshape.com/api/v6/partstudios/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' \
  -d '{
      "feature" : {
        "btType": "BTMSketch-151", 
        "featureType": "newSketch", 
        "name": "Sketch 1", 
        "parameters": [
          {
            "btType": "BTMParameterQueryList-148",
            "queries": [
              {
                "btType": "BTMIndividualQuery-138",
                "deterministicIds": [ "JCC" ] 
              }
            ],
            "parameterId": "sketchPlane" 
          }
        ],
        "entities": [
          {
            "btType": "BTMSketchCurve-4",
            "geometry": {
              "btType": "BTCurveGeometryCircle-115",
              "radius": 0.025,  
              "xcenter": 0.05,
              "ycenter": 0.05,  
              "xdir": 1,
              "ydir": 0, 
              "clockwise": false 
            },
            "centerId": "circle-entity.center",
            "entityId": "circle-entity"
          }  
        ],
        "constraints": [      
        ]
      }
    }'
  5. Find the new sketch’s featureId in the call response. You’ll need this for the Create a cylinder tutorial.
  6. Open your Part Studio and confirm that the sketch has been added:

    circle sketch created via features api

Create a cylinder

In this tutorial, we’ll extrude an sketch with the following properties:

Extrude dialog in Onshape UI

  1. This tutorial expands on the Create a sketch tutorial. You’ll need the following from the document containing your circular sketch:
    • Document ID
    • Workspace ID
    • Element ID of the tab containing the sketch
    • Feature ID of the sketch
      • If you need to get this featureId again, you can call the getPartStudioFeatures endpoint on the document.
  2. Begin to create the PartStudio/addPartStudioFeature call. Replace the URL parameters with the values from your document, and replace CREDENTIALS with your authorization credentials.
    curl -X 'POST \
  'https://cad.onshape.com/api/v6/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>
      }'
  3. Creating an extrude has many options; this means creating an extrude in the API requires adding a lot of parameters, even if they’re not used. To make this tutorial a little easier to follow, we’ll start by constructing the JSON with all available parameters, then we’ll fill in the ones we need to manipulate. Note the btType and featureType added below:
  {
  "features": [
    {
      "btType": "BTMFeature-134",
      "featureType": "extrude",
      "name": "Extrude 1",
      "suppressed": false,
      "parameters": [
        {
          "btType": "BTMParameterEnum-145",
          "parameterId": "bodyType"
        },
        {
          "btType": "BTMParameterEnum-145",
          "parameterId": "operationType"
        },
        {
          "btType": "BTMParameterQueryList-148",
          "parameterId": "entities"
        },
        {
          "btType": "BTMParameterEnum-145",
          "parameterId": "endBound"
        },
        {
          "btType": "BTMParameterQuantity-147",
          "parameterId": "depth"
        },
        {
          "btType": "BTMParameterEnum-145",
          "parameterId": "domain"
        },
        {
          "btType": "BTMParameterEnum-145",
          "parameterId": "surfaceOperationType"
        },
        {
          "btType": "BTMParameterEnum-145",
          "parameterId": "flatOperationType"
        },
        {
          "btType": "BTMParameterQueryList-148",
          "parameterId": "surfaceEntities"
        },
        {
          "btType": "BTMParameterQueryList-148",
          "parameterId": "wallShape"
        },
        {
          "btType": "BTMParameterBoolean-144",
          "parameterId": "midplane"
        },
        {
          "btType": "BTMParameterQuantity-147",
          "parameterId": "thickness1"
        },
        {
          "btType": "BTMParameterBoolean-144",
          "parameterId": "flipWall"
        },
        {
          "btType": "BTMParameterQuantity-147",
          "parameterId": "thickness2"
        },
        {
          "btType": "BTMParameterQuantity-147",
          "parameterId": "thickness"
        },
        {
          "btType": "BTMParameterEnum-145",
          "parameterId": "endBound"
        },
        {
          "btType": "BTMParameterBoolean-144",
          "parameterId": "oppositeDirection"
        },
        {
          "btType": "BTMParameterQueryList-148",
          "parameterId": "endBoundEntityFace"
        },
        {
          "btType": "BTMParameterQueryList-148",
          "parameterId": "endBoundEntityBody"
        },
        {
          "btType": "BTMParameterQueryList-148",
          "parameterId": "endBoundEntityVertex"
        },
        {
          "btType": "BTMParameterBoolean-144",
          "parameterId": "hasOffset"
        },
        {
          "btType": "BTMParameterQuantity-147",
          "parameterId": "offsetDistance"
        },
        {
          "btType": "BTMParameterBoolean-144",
          "parameterId": "offsetOppositeDirection"
        },
        {
          "btType": "BTMParameterBoolean-144",
          "parameterId": "hasExtrudeDirection"
        },
        {
          "btType": "BTMParameterQueryList-148",
          "parameterId": "extrudeDirection"
        },
        {
          "btType": "BTMParameterBoolean-144",
          "parameterId": "startOffset"
        },
        {
          "btType": "BTMParameterEnum-145",
          "parameterId": "startOffsetBound"
        },
        {
          "btType": "BTMParameterQuantity-147",
          "parameterId": "startOffsetDistance"
        },
        {
          "btType": "BTMParameterBoolean-144",
          "parameterId": "startOffsetOppositeDirection"
        },
        {
          "btType": "BTMParameterQueryList-148",
          "parameterId": "startOffsetEntity"
        },
        {
          "btType": "BTMParameterBoolean-144",
          "parameterId": "symmetric"
        },
        {
          "btType": "BTMParameterBoolean-144",
          "parameterId": "hasDraft"
        },
        {
          "btType": "BTMParameterQuantity-147",
          "parameterId": "draftAngle"
        },
        {
          "btType": "BTMParameterBoolean-144",
          "parameterId": "draftPullDirection"
        },
        {
          "btType": "BTMParameterBoolean-144",
          "parameterId": "hasSecondDirection"
        },
        {
          "btType": "BTMParameterEnum-145",
          "parameterId": "secondDirectionBound"
        },
        {
          "btType": "BTMParameterBoolean-144",
          "parameterId": "secondDirectionOppositeDirection"
        },
        {
          "btType": "BTMParameterQuantity-147",
          "parameterId": "secondDirectionDepth"
        },
        {
          "btType": "BTMParameterQueryList-148",
          "parameterId": "secondDirectionBoundEntityFace"
        },
        {
          "btType": "BTMParameterQueryList-148",
          "parameterId": "secondDirectionBoundEntityBody"
        },
        {
          "btType": "BTMParameterQueryList-148",
          "parameterId": "secondDirectionBoundEntityVertex"
        },
        {
          "btType": "BTMParameterBoolean-144",
          "parameterId": "hasSecondDirectionOffset"
        },
        {
          "btType": "BTMParameterQuantity-147",
          "parameterId": "secondDirectionOffsetDistance"
        },
        {
          "btType": "BTMParameterBoolean-144",
          "parameterId": "secondDirectionOffsetOppositeDirection"
        },
        {
          "btType": "BTMParameterBoolean-144",
          "parameterId": "hasSecondDirectionDraft"
        },
        {
          "btType": "BTMParameterQuantity-147",
          "parameterId": "secondDirectionDraftAngle"
        },
        {
          "btType": "BTMParameterBoolean-144",
          "parameterId": "secondDirectionDraftPullDirection"
        },
        {
          "btType": "BTMParameterBoolean-144",
          "parameterId": "defaultScope"
        },
        {
          "btType": "BTMParameterQueryList-148",
          "parameterId": "booleanScope"
        },
        {
          "btType": "BTMParameterBoolean-144",
          "parameterId": "defaultSurfaceScope"
        },
        {
          "btType": "BTMParameterQueryList-148",
          "parameterId": "booleanSurfaceScope"
        }
      ]
    }
  ]
}
  1. Now, we’ll add values for the options we want. Just like when creating an extrude within the Onshape UI, we’ll specify that the extrude is a Solid, New, Blind extrude of our sketch (we’ll specify the sketch by its featureId), with a depth of 1 inch. We’ll leave the rest of the parameters as they are.
  {
    "btType": "BTMParameterEnum-145",
    "value": "SOLID",
    "enumName": "ExtendedToolBodyType",
    "parameterId": "bodyType"
  },
  {
    "btType": "BTMParameterEnum-145",
    "value": "NEW",
    "enumName": "NewBodyOperationType",
    "parameterId": "operationType"
  },
  {
    "btType": "BTMParameterQueryList-148",
    "queries": [
      {
        "btType": "BTMIndividualSketchRegionQuery-140",
        "featureId": "{featureId}"
      }
    ],
    "parameterId": "entities"
  },
  {
    "btType": "BTMParameterEnum-145",
    "value": "BLIND",
    "enumName": "BoundingType",
    "parameterId": "endBound"
  },
  {
    "btType": "BTMParameterQuantity-147",
    "expression": "1 in",
    "parameterId": "depth"
  }
  1. Now our JSON is complete, and we can make our call.
  curl -X 'POST \
    'https://cad.onshape.com/api/v6/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 '{
        "features": [
          {
            "btType": "BTMFeature-134",
            "featureType": "extrude",
            "name": "Extrude 1",
            "suppressed": false,
            "parameters": [
              {
                "btType": "BTMParameterEnum-145",
                "value": "SOLID",
                "enumName": "ExtendedToolBodyType",
                "parameterId": "bodyType"
              },
              {
                "btType": "BTMParameterEnum-145",
                "value": "NEW",
                "enumName": "NewBodyOperationType",
                "parameterId": "operationType"
              },
              {
                "btType": "BTMParameterQueryList-148",
                "queries": [
                  {
                    "btType": "BTMIndividualSketchRegionQuery-140",
                    "featureId": "FBMwlCB9CZS8uWY_0"
                  }
                ],
                "parameterId": "entities"
              },
              {
                "btType": "BTMParameterEnum-145",
                "value": "BLIND",
                "enumName": "BoundingType",
                "parameterId": "endBound"
              },
              {
                "btType": "BTMParameterQuantity-147",
                "expression": "1 in",
                "parameterId": "depth"
              },
              {
                "btType": "BTMParameterEnum-145",
                "parameterId": "domain"
              },
              {
                "btType": "BTMParameterEnum-145",
                "parameterId": "surfaceOperationType"
              },
              {
                "btType": "BTMParameterEnum-145",
                "parameterId": "flatOperationType"
              },
              {
                "btType": "BTMParameterQueryList-148",
                "parameterId": "surfaceEntities"
              },
              {
                "btType": "BTMParameterQueryList-148",
                "parameterId": "wallShape"
              },
              {
                "btType": "BTMParameterBoolean-144",
                "parameterId": "midplane"
              },
              {
                "btType": "BTMParameterQuantity-147",
                "parameterId": "thickness1"
              },
              {
                "btType": "BTMParameterBoolean-144",
                "parameterId": "flipWall"
              },
              {
                "btType": "BTMParameterQuantity-147",
                "parameterId": "thickness2"
              },
              {
                "btType": "BTMParameterQuantity-147",
                "parameterId": "thickness"
              },
              {
                "btType": "BTMParameterEnum-145",
                "parameterId": "endBound"
              },
              {
                "btType": "BTMParameterBoolean-144",
                "parameterId": "oppositeDirection"
              },
              {
                "btType": "BTMParameterQueryList-148",
                "parameterId": "endBoundEntityFace"
              },
              {
                "btType": "BTMParameterQueryList-148",
                "parameterId": "endBoundEntityBody"
              },
              {
                "btType": "BTMParameterQueryList-148",
                "parameterId": "endBoundEntityVertex"
              },
              {
                "btType": "BTMParameterBoolean-144",
                "parameterId": "hasOffset"
              },
              {
                "btType": "BTMParameterQuantity-147",
                "parameterId": "offsetDistance"
              },
              {
                "btType": "BTMParameterBoolean-144",
                "parameterId": "offsetOppositeDirection"
              },
              {
                "btType": "BTMParameterBoolean-144",
                "parameterId": "hasExtrudeDirection"
              },
              {
                "btType": "BTMParameterQueryList-148",
                "parameterId": "extrudeDirection"
              },
              {
                "btType": "BTMParameterBoolean-144",
                "parameterId": "startOffset"
              },
              {
                "btType": "BTMParameterEnum-145",
                "parameterId": "startOffsetBound"
              },
              {
                "btType": "BTMParameterQuantity-147",
                "parameterId": "startOffsetDistance"
              },
              {
                "btType": "BTMParameterBoolean-144",
                "parameterId": "startOffsetOppositeDirection"
              },
              {
                "btType": "BTMParameterQueryList-148",
                "parameterId": "startOffsetEntity"
              },
              {
                "btType": "BTMParameterBoolean-144",
                "parameterId": "symmetric"
              },
              {
                "btType": "BTMParameterBoolean-144",
                "parameterId": "hasDraft"
              },
              {
                "btType": "BTMParameterQuantity-147",
                "parameterId": "draftAngle"
              },
              {
                "btType": "BTMParameterBoolean-144",
                "parameterId": "draftPullDirection"
              },
              {
                "btType": "BTMParameterBoolean-144",
                "parameterId": "hasSecondDirection"
              },
              {
                "btType": "BTMParameterEnum-145",
                "parameterId": "secondDirectionBound"
              },
              {
                "btType": "BTMParameterBoolean-144",
                "parameterId": "secondDirectionOppositeDirection"
              },
              {
                "btType": "BTMParameterQuantity-147",
                "parameterId": "secondDirectionDepth"
              },
              {
                "btType": "BTMParameterQueryList-148",
                "parameterId": "secondDirectionBoundEntityFace"
              },
              {
                "btType": "BTMParameterQueryList-148",
                "parameterId": "secondDirectionBoundEntityBody"
              },
              {
                "btType": "BTMParameterQueryList-148",
                "parameterId": "secondDirectionBoundEntityVertex"
              },
              {
                "btType": "BTMParameterBoolean-144",
                "parameterId": "hasSecondDirectionOffset"
              },
              {
                "btType": "BTMParameterQuantity-147",
                "parameterId": "secondDirectionOffsetDistance"
              },
              {
                "btType": "BTMParameterBoolean-144",
                "parameterId": "secondDirectionOffsetOppositeDirection"
              },
              {
                "btType": "BTMParameterBoolean-144",
                "parameterId": "hasSecondDirectionDraft"
              },
              {
                "btType": "BTMParameterQuantity-147",
                "parameterId": "secondDirectionDraftAngle"
              },
              {
                "btType": "BTMParameterBoolean-144",
                "parameterId": "secondDirectionDraftPullDirection"
              },
              {
                "btType": "BTMParameterBoolean-144",
                "parameterId": "defaultScope"
              },
              {
                "btType": "BTMParameterQueryList-148",
                "parameterId": "booleanScope"
              },
              {
                "btType": "BTMParameterBoolean-144",
                "parameterId": "defaultSurfaceScope"
              },
              {
                "btType": "BTMParameterQueryList-148",
                "parameterId": "booleanSurfaceScope"
              }
            ]
          }
        ]
      }'
  1. Open your document and confirm that the sketch has been extruded into a cylinder.

    circle sketch created via features api

Update a feature

In this example we’ll update our cube feature.

  1. Open the document in which you created the cube feature in this example. You will need the following from this document:
    • Document ID
    • Workspace ID
    • Element ID (for the element that contains the cube feature)
    • Feature ID (ID of the cube feature, returned in the API response in the previous example)
      • If you need to get this featureId again, you can call the getPartStudioFeatures endpoint on the document.
  2. Begin to create the PartStudio/updatePartStudioFeature call. Replace the URL parameters with the values from your document, and replace CREDENTIALS with your authorization credentials.
    curl -X 'POST' \
  'https://cad.onshape.com/api/v6/partstudios/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' \
  -d '{
          <JSON of feature data>
      }'
  3. Add the following as the JSON body.
    • Note the btType defines this as a Feature.
    • We specify the featureId again in the request body. This must match the featureId sent in the URL exactly.
    • We must also specify the feature’s featureType and name in this call; if we don’t send those fields, the call will attempt to change these values to empty strings, resulting in errors.
    • The cube feature has one parameter– the cube sideLength in inches, which we will update to 2 inches:
    {
  "btType": "BTFeatureDefinitionCall-1406",
  "feature": {
    "featureId": "{fid}",
    "featureType": "cube",
    "name": "Cube 1",
    "parameters": [
      {
              "btType": "BTMParameterQuantity-147",
              "isInteger": false,
              "expression": "2 in",
              "parameterId": "sideLength"
            }
    ]
  }
}
  4. Confirm your call matches the following, and then make the call:
        curl -X 'POST' \
      'https://cad.onshape.com/api/v6/partstudios/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' \
      -d '{
      "btType": "BTFeatureDefinitionCall-1406",
      "feature": {
        "featureId": "{fid}",
        "featureType": "cube",
        "name": "Cube 1",
        "parameters": [
              {
                "btType": "BTMParameterQuantity-147",
                "isInteger": false,
                "expression": "2 in",
                "parameterId": "sideLength"
              }
          ]  
        }
    }'
  5. Return to your console to review the endpoint response. The output returns:
    • The updated feature definition
    • Information that the feature executed correctly
    • The serialization version and microversion of the document that resulted from the feature update
      {
    "btType": "BTFeatureDefinitionResponse-1617",
    "featureState": {
      "btType": "BTFeatureState-1688",
      "featureStatus": "OK",
      "inactive": false
    },
    "feature": {
      "btType": "BTMFeature-134",
      "name": "Cube 1",
      "suppressed": false,
      "parameters": [
        {
          "btType": "BTMParameterQuantity-147",
          "value": 0,
          "units": "",
          "isInteger": false,
          "expression": "2 in",
          "nodeId": "{nid1}",
          "parameterId": "sideLength"
        }
      ],
      "featureId": "{fid}",
      "nodeId": "{nid2},
      "featureType": "cube",
      "returnAfterSubfeatures": false,
      "subFeatures": [],
      "namespace": ""
    },
    "serializationVersion": "1.2.4",
    "sourceMicroversion": "{mid}",
    "microversionSkew": false,
    "rejectMicroversionSkew": false,
    "libraryVersion": 0
  }
  6. Open your document and confirm that the cube has a side length of 2 inches.
    cube added to part studio via features api

Delete a feature

  1. Create a new document and add a cube feature to it. See Create a cube feature for instructions. Make a note of the following:
    • Document ID
    • Workspace ID
    • Element ID (for the element containing the cube feature)
  2. Call the getPartStudioFeatures endpoint on the document to get the featureId of the cube feature. See Get the Feature list for instructions.
  3. Create and execute the PartStudio/deletePartStudioFeature call. Replace the URL parameters with the values from your document, and replace CREDENTIALS with your authorization credentials.
    curl -X 'DELETE' \
  'https://cad.onshape.com/api/v6/partstudios/d/{did}/w/{wid}/e/{eid}/features/featureid/{fid}' \
  -H 'Accept: application/json;charset=UTF-8; qs=0.09' \
  -H 'Authorization: Basic CREDENTIALS'
  4. Confirm that the cube feature has been removed from your document.