Release Management

This page describes the APIs Onshape provides for viewing revisions and for creating, submitting, approving, and publishing releases.

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.
See API Guide: API Intro for information on what these IDs mean and how to obtain them from your documents.
Variables are written as: {variableId1} or <variableIdTwo>.
These represent variables that must be replaced in the code before it is usable.
Never include the braces {} or angle brackets <> with your IDs/variables.
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.

Custom Workflows

Enterprise administrators can create customized release and obsoletion workflows. See the following Onshape Help article on designing release management processes for your Enterprise: Designing Release Management Processes.

Examples

Note:
Workflow IDs and property IDs are stable across your company or enterprise. You only need to GET these IDs once.

Create a release candidate

Create a release candidate and add items to the release in the items array. This example creates a release candidate with one part. Items can also be added to the release later with the updateRelease endpoint.

Notes:
The response includes an id; this is your release candidate package ID (rpid).
This ID cannot easily be obtained later from a different endpoint, so store it securely.
This ID can be obtained later from the Onshape UI: Review the release candidate in the UI and click the Copy link icon. The release ID is included at the end of the copied URL.
To add items from other documents, you must select Allow adding items from other documents in your Release Management settings.

Endpoint

createReleasePackage - POST /releasepackages/release/{wfid}

Parameters

wfid - Workflow ID
- Call getActiveWorkflows
  - This endpoint takes documentId and not the usual did.
- Response field - releaseWorkflow.id
  - The default releaseWorkflow.name is "Onshape default release workflow".
  - To use a custom workflow, find the releaseWorkflow.id field for the releaseWorkflow.name to use.

Request Body

{
  "items": [
    {
      "documentId": <did>,
      "elementId": <eid>,
      "partId": <partId>,
      "versionId": <vid>
    }
  ]
}

Example

wfid - Get ID of the workflow to use for the release.
- Call getActiveWorkflows
  - This endpoint takes documentId and not the usual did.
- Response field - releaseWorkflow.id
Create a document with one Part Studio that contains at least one part:
- did - Document ID
- eid - Element ID of the Part Studio
partId - Get the ID of Part 1:
- Call getPartsWMVE
- Response field - partId
vid - Create a version in the document.
- Call createVersion.
- Provide the document documentId and workspaceId in the request body.
- Provide a name for the version in the request body.

Create the release candidate:

curl -X 'POST' \
'https://cad.onshape.com/api/v14/releasepackages/release/{wfid}?debugMode=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' \
-d '{
  "items": [
    {
      "documentId": "{did}",
      "elementId": "{eid}",
      "partId": "{partId}",
      "versionId": "{vid}"
    }
  ]
}'

rpid - The release candidate is created, and contains only the first part from the Part Studio. Find the id at the end of the response. This is the release ID.

Add items to a release candidate

This example adds items to an existing release candidate.

Endpoint

updateReleasePackage - POST /releasepackages/{rpid}

Parameters

rpid - ID of the release candidate to update
action - "ADD_ITEMS"

Request Body

{
  "items": [
    {
      "documentId": <did>,
      "elementId": <eid>,
      "partId": <partIdTwo>,
      "versionId": <vid>
    },
    {
      "documentId": <did>,
      "elementId": <eid>,
      "partId": <partIdThree>,
      "versionId": <vid>
    }
  ]
}

Example

Complete the Create a release candidate example before this one.

rpid - ID of the release candidate to update.
did, vid, and eid - Document, version, and element that contain the parts to add.

Add two parts to the document.
partId - Get the IDs of the two new parts:
- Call getPartsWMVE
- Response field - partId for the new parts.

Call the updateReleasePackage endpoint:

curl -X 'POST' \
'https://cad.onshape.com/api/v14/releasepackages/{rpid}?action=ADD_ITEMS' \
-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": [
    {
      "documentId": "{did}",
      "elementId": "{eid}",
      "partId": "{partIdTwo}",
      "versionId": "{vid}"
    },
    {
      "documentId": "{did}",
      "elementId": "{eid}",
      "partId": "{partIdThree}",
      "versionId": "{vid}"
    }
  ]
}'

The response indicates that all three parts are now in the release candidate.

View release candidate details

View release candidate properties and all existing items included in the release.

Endpoint

getReleasePackage - GET /releasepackages/{rpid}

Parameters

rpid - ID of the release candidate to update
detailed - true | false

Example

rpid - ID of the release candidate to update. Complete the Create a release candidate example before this one.

Call the getReleasePackage endpoint:

curl -X 'GET' \
  'https://{baseUrl}.onshape.com/api/v14/releasepackages/{rpid}?detailed=false' \
  -H 'Accept: application/json;charset=UTF-8; qs=0.09' \
  -H 'Authorization: Basic CREDENTIALS'

In the response, find the items array. Each item included in the release appears in the array and includes an items.id and an array of items.properties.
Find the workflow.state.name field. This is the current state of the release.
Find the workflow object and make a note of each available workflow.actions.action. These are your available wfaction strings that can be used to transition the workflow to a different state. You’ll need these if you want to submit or release the candidate later.

Remove items from a release candidate

This example removes parts from an existing release candidate. See View release candidate details to obtain a list of item IDs that can be removed.

Endpoint

updateReleasePackage - POST /releasepackages/{rpid}

Parameters

rpid - ID of the release candidate to update
action - "REMOVE_ITEMS"

Request Body

{
  "itemIds": [ <itemIdTwo>, <itemIdThree> ]
}

Example

rpid - ID of the release candidate to update. Complete the Create a release candidate example to get this id.
itemIds - The items to remove
- Complete the Add items to a release candidate to add the items we’ll now remove.
- Complete the View release candidate details to get the IDs of items to remove. There should be three items total. We will remove the two we just added, leaving only the original item in the release.

Call the updateReleasePackage endpoint:

  curl -X 'POST' \
  'https://{baseUrl}.onshape.com/api/v14/releasepackages/{rpid}?action=REMOVE_ITEMS' \
  -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 '{
    "itemIds": [ "{itemIdTwo}", "{itemIdThree}" ]
  }'

Repeat the View release candidate details example to confirm that only one part is left in the release candidate.

Get all revisions

The following endpoints all return revision information for the specified items:

Item	Endpoint	Path
Company	`enumerateRevisions`	GET /revisions/companies/{cid}
Document	`getAllInDocument`	GET /revisions/d/{did}
Version	`getAllInDocumentVersion`	GET /revisions/d/{did}/v/{vid}
Element	`getRevisionHistoryInCompanyByElementId`	GET /revisions/companies/{cid}/d/{did}/{wv}/{wvid}/e/{eid}
Part number	`getRevisionHistoryInCompanyByPartNumber`	GET /revisions/companies/{cid}/partnumber/{pnum}
Part ID	`getRevisionHistoryInCompanyByPartId`	GET /revisions/companies/{cid}/d/{did}/e/{eid}/p/{pid}

Parameters

elementType or et: Element type
- See the API Explorer for a full list for allowed values and additional parameter options.
- View instructions on locating the request body docs in the API Explorer: View request body docs as needed.

Example

cid - Company ID
- Call findCompany
- Response field - id (NOT address.id or ownerId)
pnum - The part number to get revision info for
- Call getPartsWMVE
- Response field - partNumber
elementType - Element type
- View the getLatestInDocumentOrCompany endpoint parameters to see available options.
- In this example, we’ll use elementType=0 to indicate the part is in a Part Studio.

Call the getRevisionByPartNumber endpoint:

curl -X 'POST' \
  'https://{baseUrl}.onshape.com/api/v14/revisions/c/{cid}/partnumber/{pnum}/?elementType=0' \
  -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/v14/revisions/c/{cid}/partnumber/{pnum}/"
queryParams = {
  "elementType": 0
}

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

Review the response, which includes information for each revision. Each item in the list includes the releaseName and revision fields.

Get latest revision info

Endpoint

getLatestInDocumentOrCompany - GET /revisions/{cd}/{cdid}/p/{pnum}/latest

Parameters

et: integer
- See the API Explorer for a full list for allowed et values and additional parameter options.
- View instructions on locating the request body docs in the API Explorer: View request body docs

Example

did - The ID of any document owned by the company.
pnum - The part number to get revision info for
- Call getPartsWMVE
- Response field - partNumber
et - Element type
- View the getLatestInDocumentOrCompany endpoint parameters to see available options.
- In this example, we’ll use et=0 to indicate the part is in a Part Studio.

Call the getLatestInDocumentOrCompany endpoint:

curl -X 'POST' \
  'https://{baseUrl}.onshape.com/api/v14/revisions/d/{did}/p/{pnum}/latest?et=0' \
  -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/v14/revisions/d/{did}/partnumber/{pnum}/"
queryParams = {
  "et": 0
}

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

Note that you could also use /c/{cid} to submit a company ID instead of a document ID. Either is acceptable.

From the response, locate the releaseName and revision fields.

Get the next available part number

Endpoint

POST /numberingscheme/nextNumbers

Query Params

{
  "cid": <cid>,
  "did": <did>
}

You must provide either the company ID or the ID of a document owned by the company.

Request Body

{
  "itemPartNumbers": [
    {
      "documentId": <did>,
      "elementId": <eid>,
      "elementType": <elementType>,
      "numberSchemeResourceTypeId": <numberSchemeResourceTypeId>,
      "partId": <partId>,
      "workspaceId": <wid>
    }
  ]
}

See the nextNumbers request body schema for a full list for allowed values for elementType and numberSchemeResourceTypeId, and for additional parameter options, including configurations.
View instructions on locating the request body docs in the API Explorer: View request body docs

Example

did - Document ID
- In the path parameter, this is the ID of any document owned by the company. This identifies the company’s numbering scheme.
- In the request body, this is the document that contains the part to get a part number for.
eid and wid - The element (tab) and workspace that contain the part to get a part number for.
partId - Part to get the next part number for:
- Call getPartsWMVE
- Response field - partId
See the nextNumbers request body schema for a full list for allowed values for elementType and numberSchemeResourceTypeId.
- Use elementType=0 to indicate a Part Studio.
- Use numberSchemeResourceTypeId="8c96700620f77935a0b2cddc" to indicate a Part Studio.

Call the endpoint:

curl -X 'POST' \
  'https://{baseUrl}.onshape.com/api/v14/numberingscheme/nextNumbers?did={did}' \
  -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 '{
      "itemPartNumbers": [
        {
          "documentId": "{did}",
          "elementId": "{eid}",
          "elementType": 0,
          "numberSchemeResourceTypeId": "8c96700620f77935a0b2cddc",
          "partId": "{partId}",
          "workspaceId": "{wid}"
        }
      ]
    }'

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/v14/numberingscheme/nextNumbers"
queryParams = {
  "did": "{did}"
}

body = {
  "itemPartNumbers": [
    {
      "documentId": "{did}",
      "elementId": "{eid}",
      "elementType": 0,
      "numberSchemeResourceTypeId": "8c96700620f77935a0b2cddc",
      "partId": "{partId}",
      "partNumber": "{partNumber}",
      "workspaceId": "{wid}"
    }
  ]
}

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

The next available partNumber is listed in the response.
You can apply this new part number when you submit the release, or as part of a metadata update.

Submit a release candidate for approval

Endpoint

POST /releasepackages/{rpid}

Parameters

rpid - ID of the release candidate to submit
action - "UPDATE"
wfaction - The workflow transition name to perform:
- Call getReleasePackage
- Response field - workflow.actions.action
- In the Onshape default release workflow, this is the SUBMIT action.
- Note the corresponding workflow.actions.requiredProperties. You need to set these in the request body properties array.

Request Body

{
  "items": [
    {
      "id": <items.id>,
      "documentId": <items.documentId>,
      "elementId": <items.elementId>,
      "versionId": <items.versionId>,
      "href": <items.href>,
      "properties": [
        {
          "propertyId": <items.properties.propertyIdRevision>,
          "value": <revisionName>
        },
        {
          "propertyId": <items.properties.propertyIdPartNumber>,
          "value": <partNumber>
        }
      ]
    }
  ],
  "properties": [
    {
      "propertyId": <properties.propertyIdApprovers>,
      "value": [{"id": <userId>}]
    }
  ]
}

Example

rpid - ID of the release candidate to update. Complete the Create a release candidate example to get this id.
Complete the View release candidate details example to obtain the following info from the response:
- wfaction
  - workflow.actions.action
  - For this example, we’ll use the SUBMIT transition from the Onshape default release workflow.
- items - For each item to release, get the following info:
  - items.id
  - items.documentId
  - items.elementId
  - items.versionId
  - items.href
- items.properties - For each item to release, get the following properties:
  - items.property.propertyIdRevision - items.properties.propertyId where items.properties.name="Revision"
  - items.property.propertyIdPartNumber - items.properties.propertyId where items.properties.name="Part number"
- properties.propertyId
  - Locate the properties.propertyId field that matches the workflows.actions.requiredProperties for your workflow action.
  - Hint: make sure you’re looking at the top-level release candidate properties, not individual items.properties
  - In this example, properties.name="Approvers", indicating that we must include approvers with our submission.
  - We’ll call this properties.propertyIdApprovers in the example for clarity.
revisionName - The new revision for the released item.
- Must be unique. See Get all revisions to see previous revisions.
- We’ll use B in this example.
partNumber - The new part number for the released item.
- Must be unique. See Get the next available part number.
- We’ll use PRT-002 in this example.
userId - The approver to submit to
- Call findCompany to get the company id.
- Call getAllowedApprovers using the company id as the cid.
- Response field - items.user.id

Submit the release:

curl -X 'POST' \
  'https://cad.onshape.com/api/v14/releasecandidates/{rpid}?action=UPDATE&wfaction=SUBMIT' \
  -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": [
          {
            "id": "{items.id}",
            "documentId": "{items.documentId}",
            "elementId": "{items.elementId}",
            "versionId": "{items.versionId}",
            "href": "{items.href}",
            "properties": [
              {
                "propertyId": "{items.property.propertyIdRevision}",
                "value": "B"
              },
              {
                "propertyId": "{items.propertyIdPartNumber}",
                "value": "PRT-002"
              }
            ]
          }
        ],
        "properties": [
          {
            "propertyId": "{properties.propertyIdApprovers}",
            "value": [{"id": "{userId}"}]
          }
        ]
    }'

The response indicates that the release candidate has been submitted for approval.

Approve a release candidate

You must be set as an approver in your Onshape settings to approve a release.

Endpoint

updateReleasePackage - POST /releasepackages/{rpid}

Parameters

rpid - ID of the release candidate to publish
action - "UPDATE"
wfaction - The workflow transition name to perform:
- Call getReleasePackage
- Response field - workflow.actions.action
- In the Onshape default release workflow, this is the RELEASE action.

Request Body

{}

Example

rpid - ID of the release candidate to update. Complete the Create a release candidate example to get this ID.
Complete the Submit a release for approval example before this one.
wfaction - The workflow transition name to perform:
- Call - getReleasePackage
- Response field - workflow.actions.action
- In this example, we’ll use the RELEASE transition from the Onshape default release workflow.

Submit the release. Note that you must send an empty json request body.

curl -X 'POST' \
  'https://cad.onshape.com/api/v14/releasepackages/{rpid}?action=UPDATE&wfaction=RELEASE' \
  -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 '{}'

Release a part without approval

Endpoint

updateReleasePackage - POST /releasepackages/{rpid}

Parameters

rpid - ID of the release candidate to publish
action - "UPDATE"
wfaction - The workflow transition name to perform:
- Call - getReleasePackage
- Response field - workflow.actions.action
- In the Onshape default release workflow, this is the CREATE_AND_RELEASE action.

Request Body

{
  "items": [
    {
      "id": <items.id>,
      "documentId": <items.documentId>,
      "elementId": <items.elementId>,
      "versionId": <items.versionId>,
      "href": <items.href>,
      "properties": [
        {
          "propertyId": <items.propertyIdRevision>,
          "value": "A"
        },
        {
          "propertyId": <items.propertyIdPartNumber>,
          "value": <items.partNumber>
        }
      ]
    }
  ]
}

Example

rpid - ID of the release candidate to update. Complete the Create a release candidate example before this one.
Complete the View release candidate details example to obtain the following information:

wfaction
- workflow.actions.action
- For this example, we’ll use the CREATE_AND_RELEASE transition from the default Onshape release workflow.
items - For each item to release, obtain the following:
- items.id
- items.documentId
- items.elementId
- items.versionId
- items.href
items.properties - For each item to release, obtain the following:
- propertyIdRevision - items.properties.propertyId where properties.name="Revision"
- propertyIdPartNumber - items.properties.propertyId where properties.name="Part number"

partNumber - See Get the next available part number.

Submit the release:

curl -X 'POST' \
  'https://cad.onshape.com/api/v14/releasepackages/{rpid}?action=UPDATE&wfaction=CREATE_AND_RELEASE' \
  -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": [
    {
      "id": "{items.id}",
      "documentId": "{items.documentId}",
      "elementId": "{items.elementId}",
      "versionId": "{items.versionId}",
      "href": "{items.href}",
      "properties": [
        {
          "propertyId": "{items.propertyIdRevision}",
          "value": "A"
        },
        {
          "propertyId": "{items.propertyIdPartNumber}",
          "value": "{items.partNumber}"
        }
      ]
    }
  ]
}'

Additional Resources

API Explorer: Revision Endpoints
API Explorer: Release Endpoints
API Guide: Using the API Explorer
Onshape Help: Release Management