Metadata

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

Prerequisites
  • All Onshape API calls must be properly authenticated.
    • 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.
  • For Standard accounts, replace {baseUrl} with cad in all endpoints. For Enterprise accounts, replace it with your company domain. Add /api and the version number, and then provide the endpoint.
    • https://{baseUrl}.onshape.com/api/v10/documents
    • https://cad.onshape.com/api/v10/documents
    • https://companySubDomain.onshape.com/api/v10/documents
  • Onshape IDs are written as: {did}, {wvmid}, {eid}, {pid}, {otherId}.
    • These represent document, workspace (or version or microversion), element, part, and other IDs, respectively.
    • Never include the braces {} with your IDs.
    • See API Guide: API Intro for information on what these IDs mean and how to obtain them from your documents.
  • This page provides sample code in cURL and python.
  • For additional instruction and video content, visit the Learning Center’s Intro to the Onshape API course.

Updating Metadata

To update metadata, you send a JSON in the API request body in the following general format:

{
  "properties": [
    {
      "value": "", // new value for the property
      "propertyId": "{propertyId}" // ID of the property
    }
  ]
}

Examples

Update a part property

Update a part’s description by getting the current metadata for the part and then posting an update to that metadata.

Endpoint

POST v10/metadata/d/{did}/w/{wid}/e/{eid}/p/{pid}

Request Body

{
  "jsonType": "metadata-part",
  "partId": "{pid}",
  "properties": [
    {
      "value": "",
      "propertyId": "{propertyId}"
    }
  ]
}

Additional optional fields available. See the API Explorer for a full list.

Example

  1. 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 endpoint on your 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. Now, get the metadata of the part by calling the getWMVEPMetadata endpoint to get the current metadata JSON for the part.
      curl -X 'GET' \
    'https://{baseUrl}.onshape.com/api/v10/metadata/d/{did}/w/{wid}/e/{eid}/p/JHD' \
    -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' 

    import requests 
import json

auth = (access_key, secret_key) # See Authentication guide
headers = {
  'Accept': 'application/json;charset=UTF-8;qs=0.09',
  'Content-Type': 'application/json;charset=UTF-8; qs=0.09'
}

api_url = "https://{baseUrl}.onshape.com/api/v10/metadata/d/{did}/w/{wid}/e/{eid}/p/JHD"

queryParams = {}

response = requests.get(  api_url, 
                          params=queryParams, 
                          auth=auth, 
                          headers=headers )
print(json.dumps(response.json(), indent=4))
  4. Locate the property to update in the response. 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; in this example, we want the propertyId for the Description property. We’ll need this ID to update the metadata.
  6. Make the updateWVEPMetadata call. Replace the {propertyId} value with the ID from the last step.
      curl -X 'POST' \
  'https://cad.onshape.com/api/v10/metadata/d/{did}/w/{wid}/e/{eid}/p/JHD' \
    -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}"
          }
        ]
        }'

    import requests 
import json

auth = (access_key, secret_key) # See Authentication guide
headers = {
  'Accept': 'application/json;charset=UTF-8;qs=0.09',
  'Content-Type': 'application/json;charset=UTF-8; qs=0.09'
}

api_url = "https://{baseUrl}.onshape.com/api/v10/metadata/d/{did}/w/{wid}/e/{eid}/p/JHD"

queryParams = {}

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

response = requests.post( api_url, 
                          params=queryParams, 
                          json=body,
                          auth=auth, 
                          headers=headers )
print(json.dumps(response.json(), indent=4))
  7. Repeat steps 3 and 4 to confirm that the Description value for the part is now Drill bit.

Update a part number

Endpoint

POST v10/metadata/d/{did}/w/{wid}/e/{eid}/p/{pid}

Request Body

{
  "jsonType": "metadata-part",
  "partId": "{pid}",
  "properties": [
    {
      "value": "newPartNumber",
      "propertyId": "{propertyId}"
    }
  ]
}

Additional optional fields available. See the API Explorer for a full list.

Example

  1. Get the next available part number for your part. See Release Management for instructions.
  2. Call getPartsWMVE on your document to get the partId to update. Use this as the pid param in the next step.
  3. Call getWMVEPMetadata to get the current metadata JSON for the part.
      curl -X 'GET' \
    'https://{baseUrl}.onshape.com/api/v10/metadata/d/{did}/w/{wid}/e/{eid}/p/{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' 

    import requests 
import json

auth = (access_key, secret_key) # See Authentication guide
headers = {
  'Accept': 'application/json;charset=UTF-8;qs=0.09',
  'Content-Type': 'application/json;charset=UTF-8; qs=0.09'
}

api_url = "https://{baseUrl}.onshape.com/api/v10/metadata/d/{did}/w/{wid}/e/{eid}/p/{pid}"
queryParams = {}

response = requests.get(  api_url, 
                          params=queryParams, 
                          auth=auth, 
                          headers=headers )
print(json.dumps(response.json(), indent=4))
  4. In the response, scroll to the Part number property object. Note the propertyId to use in the next step. Also note the value– this is the current part number that we will update.
    {
      "properties": [
        {
          "name": "Part number",
          "value": "PRT-001",
          "defaultValue": null,
          "computedPropertyError": null,
          "computedPropertyEvalInfo": null,
          "aggregationSkippedFilteredOutValues": false,
          "required": false,
          "validator": {},
          "propertySource": 3,
          "editable": true,
          "valueType": "STRING",
          "propertyId": "{propertyId}",
          "editableInUi": true,
          "dateFormat": null,
          "enumValues": null,
          "schemaId": "string",
          "multivalued": false,
          "uiHints": {},
          "computedAssemblyProperty": false,
          "computedProperty": false,
          "propertyOverrideStatus": 0
      }]
  }
  1. Call updateWVEPMetadata. Replace the {propertyId} value with the ID from the last step, and replace value with your desired part number. See Release Management for steps on getting the next valid available part number to use.
      curl -X 'POST' \
  'https://cad.onshape.com/api/v10/metadata/d/{did}/w/{wid}/e/{eid}/p/{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",
          "partId": "{pid}",
          "properties": [
            {
              "value": "PRT-002",
              "propertyId": "{propertyId}"
            }
          ]
        }'

    import requests 
import json

auth = (access_key, secret_key) # See Authentication guide
headers = {
  'Accept': 'application/json;charset=UTF-8;qs=0.09',
  'Content-Type': 'application/json;charset=UTF-8; qs=0.09'
}

api_url = "https://{baseUrl}.onshape.com/api/v10/metadata/d/{did}/w/{wid}/e/{eid}/p/{pid}"

queryParams = {}

body = {
  "jsonType": "metadata-part",
  "partId": "{pid}",
  "properties": [
    {
    "value": "PRT-002",
    "propertyId": "{propertyId}"
    }
  ]
}

response = requests.post( api_url, 
                          params=queryParams, 
                          json=body,
                          auth=auth, 
                          headers=headers )
print(json.dumps(response.json(), indent=4))
  2. Repeat steps 2 and 3 to confirm that the value for the part is now PRT-002.

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.

Endpoint

POST api/v10/metadata/d/{did}/w/{wid}/e/{eid}

Request Body

{
  "properties": [
    {
      "value": "",
      "propertyId": "{propertyId}"
    }
  ]
}

  1. 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”.

    Onshape document with NEW_PART tab name

  2. To get the current metadata of the element, 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 new document, and replace CREDENTIALS with your authorization credentials.

    curl -X 'GET' \
    'https://cad.onshape.com/api/v10/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' 

    import requests 
import json

auth = (access_key, secret_key) # See Authentication guide
headers = {
  'Accept': 'application/json;charset=UTF-8;qs=0.09',
  'Content-Type': 'application/json;charset=UTF-8; qs=0.09'
}

api_url = "https://{baseUrl}.onshape.com/api/v10/metadata/d/{did}/w/{wid}/e/{eid}"
queryParams = {}

response = requests.get(  api_url, 
                          params=queryParams, 
                          auth=auth, 
                          headers=headers )
print(json.dumps(response.json(), indent=4))

  3. 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. Copy the Name block’s propertyId in the response. We’ll need this ID to update the metadata.

  5. Set up the updateWVEMetadata call.

    Note that we need to include the propertyId and the value to update. In the request JSON, replace {propertyId} with the property ID you found in the last step, then change the empty value string to "PISTON":

    curl -X 'POST' \
'https://cad.onshape.com/api/v10/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}"
            }
            ]
        }'

    import requests 
import json

auth = (access_key, secret_key) # See Authentication guide
headers = {
  'Accept': 'application/json;charset=UTF-8;qs=0.09',
  'Content-Type': 'application/json;charset=UTF-8; qs=0.09'
}

api_url = "https://{baseUrl}.onshape.com/api/v10/metadata/d/{did}/w/{wid}/e/{eid}"
queryParams = {}
body = {
  "properties": [
      {
          "value": "PISTON",
          "propertyId": "{propertyId}"
      }
      ]
  }

response = requests.post( api_url, 
                          params=queryParams, 
                          json=body,
                          auth=auth, 
                          headers=headers )
print(json.dumps(response.json(), indent=4))

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

    Onshape document with NEW_PART tab name

Update standard content part metadata

Standard Content Notes
  • {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.

Endpoint

POST api/v10/metadata/standardcontent/d/{did}

Request Body

{
  "items": [
    {
    "href": "https://{baseUrl}.onshape.com/api/v10/metadata/standardcontent/d/{did}/v/{vid}/e/{eid}/c/{companyId}/p/{pid}?configuration={config}&linkDocumentId={linkDocumentId}&applyToAllConfigs=true",
    "properties": [
      { 
        "value": "", 
        "propertyId": "{propertyId1}" 
      },
      { 
        "value": "", 
        "propertyId": "{propertyId2}" 
      }
    ]
    }
  ]
}

Additional Resources