Import & Export

This page describes the APIs Onshape provides for importing files to Onshape and exporting files from Onshape into different formats. We refer to the process of importing and exporting files from one format to another as translating the files.

Onshape provides several APIs to support this format translation. These fall into three categories:

📘 Notes

  • This page provides sample code as curls. See the curl documentation for more information.
  • All Onshape API calls must be properly authenticated by replacing the CREDENTIALS variable in the curls below. See the API Keys page for instructions and the Quick Start for an example. All applications submitted to the Onshape App Store must authenticate with OAuth2.
  • This documentation refers to Onshape IDs in the following format: {did}, {wid}, {eid}, {pid}, {otherId}. These represent document, workspace, element, part, and other IDs (respectively) that are needed make the API calls. We sometimes abbreviate these variables as DWVEM Please see API Guide: API Intro for information on what these IDs mean and how to obtain them from your documents. Never include the curly braces ({}) in your API calls.
  • For Enterprise accounts, replace cad in all Onshape URLs with your company domain. https://cad.onshape.com > https://companyName.onshape.com

Synchronous exports

Onshape provides a simple way to export content to common formats (glTF, Parasolid, and STL). Most of the interfaces defined here operate by requesting an HTTP redirect to a different URL where the request is fulfilled. Applications must explicitly handle the redirect and attachment authentication headers to the follow-up request, or it will fail.

The following endpoints are available. We’ve included an example curl with each one.

  • Export Part to glTF
    curl -X 'GET' \
  'https://cad.onshape.com/api/v6/parts/d/{did}/w/{wid}/e/{eid}/partid/{partid}/gltf?rollbackBarIndex=-1&outputSeparateFaceNodes=false&outputFaceAppearances=false' \
  -H 'accept: model/gltf-binary;qs=0.08' \
  • Export Part to Parasolid
    curl -X 'GET' \
  'https://cad.onshape.com/api/v6/parts/d/{did}/w/{wid}?elementId={eid}&withThumbnails=false&includePropertyDefaults=false' \
  -H 'accept: application/json;charset=UTF-8; qs=0.09'
  • Export Part to STL
    curl -X 'GET' \
  'https://cad.onshape.com/api/v6/parts/d/{did}/w/{wid}/e/{eid}/partid/{partid}/stl?mode=text&grouping=true&scale=1&units=inch' \
  -H 'accept: application/octet-stream'
  • Export PartStudio to glTF
    curl -X 'GET' \
  'https://cad.onshape.com/api/v6/partstudios/d/{did}/w/{wid}/e/{eid}/gltf?rollbackBarIndex=-1&outputSeparateFaceNodes=false&outputFaceAppearances=false' \
  -H 'accept: model/gltf-binary;qs=0.08'
  • Export PartStudio to Parasolid
    curl -X 'GET' \
  'https://cad.onshape.com/api/v6/partstudios/d/{did}/w/{wid}/e/{eid}/parasolid?version=0&includeExportIds=false&binaryExport=false' \
  -H 'accept: */*'
  • Export PartStudio to STL
    curl -X 'GET' \
  'https://cad.onshape.com/api/v6/partstudios/d/{did}/w/{wid}/e/{eid}/stl?mode=text&grouping=true&scale=1&units=inch' \
  -H 'accept: */*'
  • Export Document to JSON
    curl -X 'POST' \
  'https://cad.onshape.com/api/v6/documents/d/{did}/w/{wid}/e/{eid}/export' \
  -H 'accept: application/octet-stream' \

Asynchronous exports

The exports in the last section perform the format translation synchronously, returning the output immediately after some processing delay. Other format conversions are more complex and time-consuming, and in many cases, cannot be completed quickly enough to prevent connection errors. Note that the source format for an export is currently always automatically detected by Onshape. Part Studios and Assemblies are known to be ONSHAPE format. File uploads have their type determined by the filename suffix. For example, a file named part7.step is assumed to be in STEP format.

The following asynchronous translation APIs are available:

These asynchronous exports include a few additional steps, which are explained in more detail in the next section:

  1. See what formats are available for exporting your content with Translation/getAllTranslatorFormats.
  • Note: Parts with mesh data cannot be exported to ACIS, IGES, or OBJ format.
  1. Call the desired translation API.
    • Specify the target formatName in the request body JSON.
    • Specify storeInDocument=false (default) to export the content to new file.
    • Specify storeInDocument=true to export the content to a blob element in the source document.
  2. Poll the requestState in the translation response and wait for a result of DONE.
  3. To retrieve the exported results:

Async export details

To export your Onshape content to another format:

  1. Determine what export format file types are available for your content by calling: Translations/getAllTranslatorFormats.
  2. Next, initiate the export by calling one of the asynchronous translation APIs.
    • Note that each of these APIs takes a JSON for specifying options for the export as part of the request body. Refer to the API Explorer page for help viewing these JSON docs.
    • The target file format must be specified in the formatName field in the request body, and must match a valid format found in Step 1.
    • By default, storeInDocument is set to false in the request body to export to a single data file (or a zip of multiple files). Set to true to export as blob elements.
  3. Wait for the translation to complete. You can either register a webhook and wait to receive a notifcation that the translation is complete (see Webhook Notifications), or you can poll the translation’s requestState:
    • You can poll the requestState from the initial translation’s response, or you can call Translation/getTranslation on the translationId from the initial translation’s response.
    • When a translation is complete, requestState will change from ACTIVE to either DONE or FAILED.
    • When requestState=DONE, results are available to be used.
  4. Retrieve the exported results:
    • If you exported to an external file, call Documents/downloadExternalData to retrieve the exported result.
      • Note that this API takes the source document ID and a “foreign ID” as required parameters.
      • Use the resultExternalDataIds from the translation response as the foreign ID (fid).
      • External data is associated with, but external to, the document used as translation context. This data is not versioned like with in-document data.
    • If your translation request body specified storeInDocument=true, retrieve the blob element data with BlobElement/downloadFileWorkspace.
      • The element IDs for the new blob elements can be found in the resultElementIds field in the translation response.

Imports

Files can be imported to Onshape as blob elements. When uploading a file to a blob element, either as a new element or an update to an existing element, if the file is a recognized format for import, it will be translated into ONSHAPE format by default. This behavior can be overridden by the application, if desired.

  • Translation/createTranslation
    curl -X 'POST' \
  'https://cad.onshape.com/api/v6/translations/d/{did}/w/{wid}' \
  -H 'accept: application/json;charset=UTF-8; qs=0.09' \
  -H 'Authorization: Basic CREDENTIALS' \
  -H 'Content-Type: multipart/form-data' \
  -F 'storeInDocument=true' \
  -F 'flattenAssemblies=true
  -F 'file=@/path/filename.ext'
  -F 'formatName=' \
  ...
  • BlobElement/uploadFileCreateElement
    curl -X 'POST' \
  'https://cad.onshape.com/api/v6/blobelements/d/{did}/w/{wid}' \
    -H 'accept: application/json;charset=UTF-8; qs=0.09' \
    -H 'Authorization: Basic CREDENTIALS' \
    -H 'Content-Type: multipart/form-data' \
    -F 'storeInDocument=true' \
    -F 'file=@/path/filename.ext'
    -F 'formatName=' \
    ...
  • BlobElement/uploadFileUpdateElement
      curl -X 'POST' \
  'https://cad.onshape.com/api/v6/blobelements/d/{did}/w/{wid}/e/{eid}' \
    -H 'accept: application/json;charset=UTF-8; qs=0.09' \
    -H 'Authorization: Basic CREDENTIALS' \
    -H 'Content-Type: multipart/form-data' \
    -F 'storeInDocument=true' \
    -F 'locationElementId=' \
    -F 'file=@/path/filename.ext'
    ...

Note that these endpoints require you to specify the target document ID and workspace ID. You must also include the file to import. These APIs also includes a request body JSON for specifying options for the import.

  • Override the translation to ONSHAPE format by specifying a valid format in the formatName field. Get a list of valid import formats by calling Translation/getAllTranslatorFormats.
  • Specify storeInDocument=true to import the data as a blob element into the target document. Change to false to only create an external data file.
  • If the source file contains an assembly and flattenAssemblies=true, the assembly structure is removed and a single part studio is created.
  • Note that when using cURL, you must begin the path to the file with an @ symbol.

Sample Workflows

Export a PartStudio to STL

We will export the CRANK PartStudio from this public document to an STL file.

  1. Call the Part Studios/exportPartStudioStl endpoint on the document:
    curl -X 'GET' \
'https://cad.onshape.com/api/v6/partstudios/d/e60c4803eaf2ac8be492c18e/w/d2558da712764516cc9fec62/e/6bed6b43463f6a46a37b4a22/stl?mode=text&grouping=true&scale=1&units=inch' \
  -H 'accept: */*'
  2. Navigate to the request URL to download the resulting STL file:
    https://cad.onshape.com/api/v6/partstudios/d/e60c4803eaf2ac8be492c18e/w/d2558da712764516cc9fec62/e/6bed6b43463f6a46a37b4a22/stl?mode=text&grouping=true&scale=1&units=inch
  3. Open the CRANK.stl file from wherever your downloads are saved.

Export a Part to Parasolid

We will export the FLYWHEEL part from this public document to an STL file.

  1. Call the Part/getPartsWMV endpoint on your document and get all the part IDs:
    curl -X 'GET' \
'https://cad.onshape.com/api/v6/parts/d/e60c4803eaf2ac8be492c18e/w/d2558da712764516cc9fec62?elementId=6bed6b43463f6a46a37b4a22&withThumbnails=false&includePropertyDefaults=false' \
  -H 'accept: application/json;charset=UTF-8; qs=0.09' \
  -H 'Authorization: Basic CREDENTIALS'
  2. Locate the part to export (hint: look for name = yourPartName) in the response body. Get the part ID from the partId field. In the example below, partId = JiD for name=FLYWHEEL:
    [
  ...
  {
    "name" : "FLYWHEEL",
    "state" : "IN_PROGRESS",
    "propertySourceTypes" : {
      "57f3fb8efa3416c06701d60f" : 3,
      "57f3fb8efa3416c06701d60d" : 3,
      "57f3fb8efa3416c06701d61e" : 3,
      "57f3fb8efa3416c06701d60e" : 3,
      "57f3fb8efa3416c06701d60c" : 3
    },
    "defaultColorHash" : "FzHLKqGeuTBFjmY_2_0",
    "ordinal" : 1,
    "isMesh" : false,
    "description" : "Flywheel",
    "microversionId" : "bdb504d2d4c948493a87ccf3",
    "partNumber" : "PRT-10241",
    "elementId" : "6bed6b43463f6a46a37b4a22",
    "partId" : "JiD",
    "bodyType" : "solid",
    "customProperties" : {
      "57f3fb8efa3416c06701d61e" : "false"
    }
  ...
]
  3. Call the Part/exportPS endpoint on the FLYWHEEL part:
    curl -X 'GET' \
'https://cad.onshape.com/api/v6/parts/d/e60c4803eaf2ac8be492c18e/w/d2558da712764516cc9fec62/e/6bed6b43463f6a46a37b4a22/partid/JiD/parasolid?version=0' \
  -H 'accept: application/octet-stream' \
  -H 'Authorization: Basic CREDENTIALS'
  4. Navigate to the request URL to download the resulting file:
    https://cad.onshape.com/api/v6/parts/d/e60c4803eaf2ac8be492c18e/w/d2558da712764516cc9fec62/e/6bed6b43463f6a46a37b4a22/partid/JiD/parasolid?version=0
  5. Open the CRANK.x_t file from your downloads. Note that the file is automatically named after the PartStudio to which the part belongs.

Export a PartStudio to SOLIDWORKS

We will export the CRANK PartStudio from this public document to a SOLIDWORKS file.

  1. Validate that SOLIDWORKS is a supported export file type by calling Translation/getAllTranslatorFormats and confirming that validDestinationFormat=true for translatorName=SOLIDWORKS.
    curl -X 'GET' \
'https://cad.onshape.com/api/v6/translations/translationformats' \
  -H 'accept: application/json;charset=UTF-8; qs=0.09'  \
  -H 'Authorization: Basic CREDENTIALS' \

    [
  {
    "validSourceFormat": true,
    "validDestinationFormat": true,
    "name": "SOLIDWORKS",
    "translatorName": "solidworks",
    "couldBeAssembly": true
  }
]
  2. Initialize the export by calling PartStudio/createPartStudioTranslation.
    curl -X 'POST' \
'https://cad.onshape.com/api/v6/partstudios/d/e60c4803eaf2ac8be492c18e/w/d2558da712764516cc9fec62/e/6bed6b43463f6a46a37b4a22/translations' \
 -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 '{
      "formatName": "SOLIDWORKS",
      "storeInDocument": false,
      "translate": true
 }'
    • Note that the API takes a JSON as part of the request body, in which you can specify options for the export.
    • In this example, we’ve just shown a snippet of the entire JSON.
    • A formatName string must be specified that matches one of the valid formats you found in the last step. In this example, we set formatName to SOLIDWORKS.
    • We want to export this to a new file, so we’ll leave storeInDocument set to false.
  3. Next, we poll the PartStudio/createPartStudioTranslation response until requestState changes from ACTIVE to DONE or FAILED.
    {
  "documentId": "e60c4803eaf2ac8be492c18e",
  "requestElementId": "6bed6b43463f6a46a37b4a22",
  "requestState": "DONE",
  "resultExternalDataIds": "[{resultId}]",
  ...
}
  4. Once requestState=DONE, we can call Documents/downloadExternalData to retrieve the exported result.
    curl -X 'GET' \
'https://cad.onshape.com/api/v6/documents/d/e60c4803eaf2ac8be492c18e/externaldata/{fid}'
    • Use the resultExternalDataIds value from the translation response as the foreign ID (fid).
    • The new SOLIDWORKS file is returned as the response and will be downloaded to wherever the API call is made.

Export an Assembly to STEP

In this example, we’ll export an assembly from this public document to a STEP file.

  1. Make a copy of this public document so you can export the assembly. Make a note of the documentId, workspaceId, and elementId of the assembly in your new document.
  2. Validate that STEP is a supported export file type for assemblies by calling Translation/getAllTranslatorFormats and confirming that validDestinationFormat=true and couldBeAssembly=true for translatorName=STEP.
    curl -X 'GET' \
'https://cad.onshape.com/api/v6/translations/translationformats' \
  -H 'accept: application/json;charset=UTF-8; qs=0.09' \
  -H 'Authorization: Basic CREDENTIALS' \

    [
  {
    "validSourceFormat": true,
    "validDestinationFormat": true,
    "name": "STEP",
    "translatorName": "step",
    "couldBeAssembly": true
  },
  ...
]
  3. Initialize the export by calling Assembly/translateFormat. Replace {did}, {wid}, and {eid} with the document, workspace, and element IDs from your copied document. Do NOT include the curly braces ({}) in the final call.
    curl -X 'POST' \
'https://cad.onshape.com/api/v6/assemblies/d/{did}/w/{wid}/e/{eid}/translations' \
  -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 '{
      "allowFaultyParts": true,
      "angularTolerance": 0.001,
      "formatName": "STEP",
      "storeInDocument": true
      }'
    • Note that the API takes a JSON as part of the request body, in which you can specify options for the export.
    • In the example above, we’ve just shown a snippet of the entire JSON where we allow faulty parts to be exported and set the angular tolerance to 0.001.
    • A formatName string must be specified that matches one of the valid formats you found in the last step. In this example, we set formatName to STEP.
    • Set storeInDocument to true to upload the STEP file as a blob element in your document.
  4. Next, we poll the Assembly/translateFormat response until requestState changes from ACTIVE to DONE or FAILED.
    {
  "resultDocumentId" : "{did}",
  "resultWorkspaceId" : "{wid}",
  "requestState" : "DONE",
  "requestElementId" : "{eid}",
  "resultExternalDataIds" : [ "{resultExternalId}" ],
  "documentId" : "{did}",
  "workspaceId" : "{wid}",
  "resultElementIds" : {resulteid},
  "name" : "GEARBOX_CHUCK",
  "id" : "{translationId}",
  "href" : "https://cad.onshape.com/api/v6/translations/{translationId}"
}
  5. Once requestState=DONE, we make a note of the resultElementId in the response. This is the elementId of the STEP blob.
  6. Now, we can call BlobElement/downloadFileWorkspace to retrieve the exported results.
    curl -X 'GET' \
'https://cad.onshape.com/api/v6/blobelements/d/{did}/w/{wid}/e/{resulteid}' \
  -H 'accept: application/octet-stream' \
  -H 'Authorization: Basic CREDENTIALS' \
    • Use the resultElementIds value from the translation response as the element ID ({resulteid}).
    • Note that you can also open your document, click the GEARBOX_CHUCK.STEP tab, and download the file from there.

Export a Drawing as a JSON

In this example, we’ll export a Drawing from this public document to a JSON file. Exporting a Drawing to JSON is useful when you need to gather information about that drawing (for example, finding valid coordinates on which to place an inspection symbol).

  1. Make a copy of this public document so you can export the assembly. Make a note of the documentId, workspaceId, and elementId of the assembly in your new document.
  2. Validate that JSON is a supported export file type for Drawings by calling Drawing/getDrawingTranslatorFormats and confirming that "name": "DRAWING_JSON" appears in the response for the drawing element in your copied document.
    curl -X 'GET' \
'https://cad.onshape.com/api/v6/drawings/d/{did}/w/{wid}/e/{eid}/translationformats' \
  -H 'accept: application/json;charset=UTF-8; qs=0.09' \
  -H 'Authorization: Basic CREDENTIALS' \

    [
  {
    "name": "DRAWING_JSON",
    "translatorName": "drawing_json",
    "couldBeAssembly": false
  },
  ...
]
  3. Initialize the export by calling Drawing/createDrawingTranslation. Replace {did}, {wid}, and {eid} with the document, workspace, and element IDs from your copied document. Do NOT include the curly braces ({}) in the final call.
    curl -X 'POST' \
  'https://cad.onshape.com/api/v6/drawings/d/{did}/w/{wid}/e/{eid}/translations' \
  -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 '{
      "formatName": "DRAWING_JSON"
      }'
    • Note that the API takes a JSON as part of the request body, in which you can specify options for the export.
    • The only required JSON field is formatName, in which we’ve specified the format as found in the getDrawingTranslatorFormats response body.
  4. Next, we poll the Drawing/createDrawingTranslation response until requestState changes from ACTIVE to DONE or FAILED.
    {
  "resultDocumentId" : "{did}",
  "resultWorkspaceId" : "{wid}",
  "requestState" : "DONE",
  "requestElementId" : "{eid}",
  "resultExternalDataIds" : [ "{resultExternalId}" ],
  "documentId" : "{did}",
  "workspaceId" : "{wid}",
  "resultElementIds" : {eid},
  "name" : "GEARBOX_CHUCK",
  "id" : "{translationId}",
  "href" : "https://cad.onshape.com/api/v6/translations/{translationId}"
}
  5. Once requestState=DONE, we make a note of the "resultElementIds" : {resulteid}, in the response. This is the element ID of the JSON blob.
  6. Now, we can call BlobElement/downloadFileWorkspace to retrieve the exported results.
    curl -X 'GET' \
'https://cad.onshape.com/api/v6/blobelements/d/{did}/w/{wid}/e/{resulteid}' \
-H 'Authorization: Basic CREDENTIALS' \
  -H 'accept: application/octet-stream'
    • Use the {resultExternalId} value from the translation response as the element ID ({resulteid}). Do not include the curly braces in your call.
    • Note that you can also open your document, click the GEARBOX_CHUCK.JSON tab, and download the file from there.

Import a Parasolid file as a Part

In this example, we’ll import the FLYWHEEL part from the CRANK.x_t file we created in the Export a Part to Parasolid example.

  1. Open or create a new Onshape document in which to import the Part. Make a note of the documentId and workspaceId of your document.
  2. Validate that Parasolid is a supported export file type for imports by calling Translation/getAllTranslatorFormats and confirming that validSourceFormat=true for translatorName=parasolid.
    curl -X 'GET' \
'https://cad.onshape.com/api/v6/translations/translationformats' \
  -H 'accept: application/json;charset=UTF-8; qs=0.09' \
  -H 'Authorization: Basic CREDENTIALS' 

    [
  {
    "validSourceFormat": true,
    "validDestinationFormat": true,
    "name": "PARASOLID",
    "translatorName": "parasolid",
    "couldBeAssembly": true
  }
]s
  3. Initialize the import by calling Translation/createTranslation. In this example, the filename is CRANK.x_t.
    curl -X 'POST' \
'https://cad.onshape.com/api/v6/translations/d/{did}/w/{wid}' \
  -H 'accept: application/json;charset=UTF-8; qs=0.09's \
  -H 'Authorization: Basic CREDENTIALS' \
  -H 'Content-Type: multipart/form-data' \
  -F 'formatName=' \
  -F 'flattenAssemblies=true' \
  -F 'translate=true' \
  -F 'file=@/pathToFile/CRANK.x_t' \
    • Replace {did} and {wid} in the URL with the document and workspace IDs for the document you want to import the part to.
    • Note that when using cURL, you must begin the path to the file with an @ symbol.
    • Note that the API takes a JSON as part of the request body, in which you can specify options for the import.
    • When importing files, the API assumes we are importing to the ONSHAPE file type. You can override this and import to a different file type using the formatName field. In this case, we can leave the formatName field blank to import to the ONSHAPE file type.
  4. Next, we poll the Translation/getDocumentTranslations response until requestState changes from ACTIVE to DONE or FAILED.
    {
  "requestState" : "DONE",
  "documentId" : "{did}",
  "workspaceId" : "{wid}",
  "resultElementIds" : [ "{resulteid}" ],
  "name" : "FLYWHEEL",
  "id" : "{id}",
  "href" : "https://cad.onshape.com/api/v1/translations/{tid}"
}
  5. Once requestState=DONE, we can view the imported file as a Part in our Onshape document. The FLYWHEEL part appears in a new PartStudio named CRANK in our document.

Export a configured part

See the Configurations API Guide for examples.

Additional Resources