Metadata

This page describes the APIs Onshape provides for working with document metadata.

📘 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

Get Metadata

• getWVMetadata: Get metadata for a workspace or version.

  curl -X 'GET' \
      'https://cad.onshape.com/api/v6/metadata/d/{did}/wv/{wvid}?inferMetadataOwner=false&depth=1&includeComputedProperties=true&includeComputedAssemblyProperties=false&thumbnail=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'
  

• getWMVEsMetadata: Get metadata for all elements in a document.

  curl -X 'GET' \
      'https://cad.onshape.com/api/v6/metadata/d/{did}/wv/{wvid}/e?inferMetadataOwner=false&depth=1&includeComputedProperties=true&includeComputedAssemblyProperties=false&thumbnail=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'
  

• getWMVEMetadata: Get metadata for an element.

  curl -X 'GET' \
      'https://cad.onshape.com/api/v6/metadata/d/{did}/wv/{wvid}/e/{eid}?inferMetadataOwner=false&depth=1&includeComputedProperties=true&includeComputedAssemblyProperties=false&thumbnail=false' \
      -H 'accept: application/json;charset=UTF-8; qs=0.09' \
      -H 'Authorization: CREDENTIALS' \
      -H 'Content-Type: application/json;charset=UTF-8; qs=0.09'
  

• getWMVEPMetadata: Get metadata for a part.

  curl -X 'GET' \
      'https://cad.onshape.com/api/v6/metadata/d/{did}/wv/{wvid}/e/{eid}/p/{pid}?rollbackBarIndex=-1&inferMetadataOwner=false&includeComputedProperties=true&includeComputedAssemblyProperties=false&thumbnail=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'
  

• getWMVEPsMetadata: Get metadata for all parts in a document.

  curl -X 'GET' \
      'https://cad.onshape.com/api/v6/metadata/d/{did}/wv/{wvid}/e/{eid}/p?inferMetadataOwner=false&includeComputedProperties=true&includeComputedAssemblyProperties=false&thumbnail=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'
  

• getVEOPStandardContentMetadata: Get metadata for a standard content part.
  • {linkedDocumentId}: ID of the document into which the standard content part is inserted.
  • You can call getAssemblyDefinition to get the other values needed for the call:
    • {did}: ID of the document in which the standard content part lives.
    • {vid}: ID of the version in which the standard content part lives.
    • {eid}: ID of the element tab in which the standard content part lives.
    • {pid}: Part ID of the standard content part.
    • {config}: Encoded configuration string.

  curl -X 'GET' \
      'https://cad.onshape.com/api/metadata/standardcontent/d/{did}/v/{vid}/e/{eid}/p/{pid}?configuration={config}&linkDocumentId={linkDocument}' \
      -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'
  

Update Metadata

To update metadata, you send a JSON in the API request body. This JSON block must include a jsonType value and a properties object array. Each object in the properties array includes a propertyId and the metadata key/value pairs.

• updateWVMetadata: Update workspace or version metadata.

  curl -X 'POST' \
      'https://cad.onshape.com/api/v6/metadata/d/{did}/wv/{wvid}' \
      -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 '{
          "jsonType": ("metadata-workspace" | "metadata-version") ,
          "properties": [
              {
                "propertyId": "propertyId1",
                "key1": "value",
                "key2": "value"
              },
              {
                "propertyId": "propertyId2",
                "key1": "value",
                "key2": "value"
              }
              ]
          }' 
  

• updateWVEMetadata: Update element metadata.

  curl -X 'POST' \
      'https://cad.onshape.com/api/v6/metadata/d/{did}/wv/{wvid}/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' \
      -d '{
          "jsonType": "metadata-element",
          "properties": [
              {
                "propertyId": "propertyId",
                "key1": "value",
                "key2": "value"
              }
              ]
          }' 
  

• updateWVEPMetadata: Update part metadata

  curl -X 'POST' \
      'https://cad.onshape.com/api/v6/metadata/d/{did}/wv/{wvid}/e/{eid}/{iden}/{pid}' \
      -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 '{
          "jsonType": "metadata-part",
          "properties": [
              {
                  "propertyId": "propertyId",
                  "key1": "value",
                  "key2": "value"
              }
              ]
          }' 
  

• updateVEOPStandardContentPartMetadata: Update standard content part metadata.
  • {linkedDocumentId}: ID of the document into which the standard content part is inserted.
  • You can call getAssemblyDefinition to get the other values needed for the call:
    • {did}, {vid}, {eid}: IDs of the document, version, and element in which the standard content part lives.
    • {companyId}: ID of the company that owns the standard content part. All metadata changes to this standard content part will populate for the entire company.
    • {pid}: Part ID of the standard content part.
    • {config}: Encoded configuration string.
  • For each items.properties object, include a unique propertyId and at least one key/value metadata pair.
  • Updates made to standard content are global for all users and documents within the company.

  curl -X 'POST' \
      'https://cad.onshape.com/api/v6/metadata/standardcontent/d/{did}?linkDocumentId={linkDocumentId}' \
      -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 '{
          "items": [
              {
              "href": "https://cad.onshape.com/api/metadata/standardcontent/d/did/v/vid/e/eid/c/companyId/p/pid?configuration=config&linkDocumentId=linkDocumentId&applyToAllConfigs=true",
              "properties": [
                  { 
                      "key": "value", 
                      "propertyId": "propertyId1" 
                  },
                  { 
                      "key": "value", 
                      "propertyId": "propertyId2" 
                  }
              ]
              }
          ]
          }'
  

Sample Workflows

Update a part property

In this example we will update a part’s description by getting the current metadata for the part, and then posting an update to that metadata.

1. Get your document information:

   Make a copy of this public document. Make a note of the new document’s document ID, workspace ID, and element ID.

2. Get the ID of the part to update:

   Call the getPartsWMVE API on your copied document to get a list of part IDs in the element. Only one part exists in the document, with a part ID of JHD.

   {
       "name": "Main",
       ...
       "microversionId": "{mid}",
       "partNumber": null,
       "elementId": "{eid}",
       "partId": "JHD",
       "bodyType": "sheet",
       ...
   }
   

3. Get the metadata of the part:

   We’ll call the getWMVEPMetadata endpoint to get the current metadata JSON for the part. Don’t forget to replace the URL parameters with the IDs from your copied document, and replace CREDENTIALS with your authorization credentials.

   curl -X 'GET' \
       'https://cad.onshape.com/api/v6/metadata/d/{did}/w/{wid}/e/{eid}/p/JHD?rollbackBarIndex=-1&inferMetadataOwner=false&includeComputedProperties=true&includeComputedAssemblyProperties=false&thumbnail=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 property to update in the response:

   The call returns a response body in JSON format. Scroll to the Description properties block of the JSON response, and notice that the value field is an empty string.

   ...
   {
       "name": "Description",
       "value": "",
       "defaultValue": null,
       "computedPropertyError": null,
       "propertySource": 3,
       "validator": { },
       "required": false,
       "editable": true,
       "propertyId": "{propertyId}",
       "editableInUi": true,
       "dateFormat": null,
       "valueType": "STRING",
       "enumValues": null,
       "multivalued": false,
       "computedAssemblyProperty": false,
       "computedProperty": false,
       "propertyOverrideStatus": 0
   },
   ...
   

5. Find the metadata’s property ID:

   Copy Description’s propertyId. We’ll need this ID to update the metadata.

6. Set up the updateWVEPMetadata call:

   curl -X 'POST' \
   'https://cad.onshape.com/api/v6/metadata/d/{did}/w/{wid}/e/{eid}/p/JHD?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' \
   

7. Add the request JSON to the call:

   Note that we need to include the jsonType, the partId, the propertyId, and the value to update.

   -d '{
       "jsonType": "metadata-part",
       "partId": "JHD",
       "properties": [
           {
               "value": "",
               "propertyId": "{propertyId}"
           }
           ]
       }'
   

8. Add the new property information:

   In the request JSON, change the empty Description value string to "Drill bit":

   -d '{
       "jsonType": "metadata-part",
       "partId": "JHD",
       "properties": [
           {
           "value": "Drill bit",
           "propertyId": "{propertyId}"
           }
           ]
       }'
   

9. POST the new metadata:

   Don’t forget to replace the URL parameters and CREDENTIALS with your information.

   curl -X 'POST' \
   'https://cad.onshape.com/api/v6/metadata/d/{did}/w/{wid}/e/{eid}/p/JHD?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 '{
       "jsonType": "metadata-part",
       "partId": "JHD",
       "properties": [
           {
           "value": "Drill bit",
           "propertyId": "{propertyId}"
           }
           ]
       }'
   

10. Confirm your changes:

    Repeat steps 3 and 4 to confirm that the Description value for the part is now Drill bit.

Update a tab name

In this example we will update an element’s tab name by getting the current metadata for the element, and then posting an update to that metadata. Remember that in Onshape, an element is typically represented as a tab in the Onshape UI.

1. Get your document information:

   Make a copy of this public document. Make a note of the new document’s document ID, workspace ID, and element ID. Note the tab name of the element is “NEW_PART”.

   
   

2. Get the metadata of the element:

   We’ll call the getWMVEMetadata endpoint to get the current metadata JSON for the element. Don’t forget to replace the URL parameters with the IDs from your copied document, and replace CREDENTIALS with your authorization credentials.

   curl -X 'GET' \
       'https://cad.onshape.com/api/v6/metadata/d/{did}/w/{wid}/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' 
   

3. Locate the property to update in the response:

   The call returns a response body in JSON format. Scroll to the Name properties block of the JSON response, and notice that the value field matches our current tab name, “NEW_PART”.

   {
       "jsonType": "metadata-element",
       "elementType": 0,
       "mimeType": "onshape/partstudio",
       "elementId": "{eid}",
       "properties": [
           {
               "name": "Name",
               "value": "NEW_PART",
               "validator": {},
               "required": true,
               "editable": true,
               "propertyId": "{propertyId}",
           },
       ...
       ],
       ...
   }
   

4. Find the metadata’s property ID:

   Copy the Name block’s propertyId in the response. We’ll need this ID to update the metadata.

5. Set up the updateWVEMetadata call:

   curl -X 'POST' \
   'https://cad.onshape.com/api/v6/metadata/d/{did}/w/{wid}/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' \
   

6. Add the request JSON to the call:

   Note that we need to include the propertyId and the value to update.

   -d '{
       "properties": [
           {
               "value": "",
               "propertyId": "{propertyId}"
           }
           ]
       }'
   

7. Add the new property information:

   In the request JSON, replace {propertyId} with the property ID you found in Step 4, then change the empty value string to "PISTON":

   -d '{
       "properties": [
           {
               "value": "PISTON",
               "propertyId": "{propertyId}"
           }
           ]
       }'
   

8. POST the new metadata:

   Don’t forget to replace the URL parameters and CREDENTIALS with your information.

   curl -X 'POST' \
   'https://cad.onshape.com/api/v6/metadata/d/{did}/w/{wid}/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' \
   -d '{
       "properties": [
           {
               "value": "PISTON",
               "propertyId": "{propertyId}"
           }
           ]
       }'
   

9. Confirm your changes:

   Open your document and confirm that the tab name is now PISTON.

   
   

Additional Resources

• API Explorer: Metadata
• API Guide: API Explorer