Drawings

This page describes the APIs Onshape provides for creating and manipulating Onshape drawings.

📘 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

To create drawings, Onshape allows you to send all drawing data points and information through the API as part of the request body JSON.

The following endpoints are available:

  • createDrawingAppElement: Create a drawing
    curl -X 'POST' \
  'https://cad.onshape.com/api/v6/drawings/d/{did}/w/{wid}/create' \
  -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 request body options from the BTDrawingParams schema>
}'
    Specify the document in which to create the drawing in the URL, and pass any additional options as part of the request body. You can provide a name for the drawing, manipulate the drawing graphics area, specify a part or template to create the drawing from, and more.
    • See documentation for all available options in the API Explorer.
    • For instructions on viewing the documentation for the request body schemas, see our API Explorer page. Check out the Sample Workflows section below for some practical examples.


      BTDrawingParams schema in the createDrawingAppElement endpoint

  • modifyDrawing: Modify a drawing and add annotations
    curl -X 'POST \
  'https://cad.onshape.doc/api/v6/drawings/d/{did}/w/{wid}/e/{eid}/modify' \
  -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 '{
      "description": "Description of the modification.",
      "jsonRequests": [ 
        {
          <JSON request body options from the jsonRequests schema>
        }
      ]
    }'
    Specify the drawing to modify in the URL, and pass the information on the modification in the request body. Note that the jsonRequests schema is not defined in the Glassworks API Explorer; see the OnshapeDrawingJson repository for this information, and check out the Sample Workflows section below for some practical examples.
  • getModificationStatus: Get the status of a drawing modification
    curl -X 'GET' \
  'https://cad.onshape.com/api/v6/drawings/modify/status/{mrid}
  -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' \
    • Provide the modification ID (from the modifyDrawing response body) to get the status of the modification.
    • This call also returns the unique IDs of any annotations that were successfully created or edited.
  • createDrawingTranslation: Export a drawing to JSON
    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"
      }'
  • getDrawingTranslatorFormats: View available drawing export formats
    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'

Errors

Status codes

If a drawing modification call fails, the modifyDrawing response will return an error, as expected. However, if the call includes multiple modifications, it will return 200 if any of the batch modifications succeed. The status field for each modification includes the status of the individual operation. For example:

{
	"status": "OK | Partial_success | Failed",
	"statusCode": "200 |207 | 400 ",
	"errorDescription": "Some Suceed and Some Faild | Failed",
	"changeId": "f19a07278a009f85f68f4526",
	"results": [
		{
			"status": "OK",
			"logicalId": "h:10000D09"
		},
		{
			"status": "OK",
			"logicalId": "h:10000D0A"
		},
		{
			"status": "Failed",
			"errorDescription": "Error processing Onshape::Note: Point reference is not an object."
		},
		{
			"status": "Failed",
			"logicalId": "h:10000C29",
			"errorDescription": "Error processing : Invalid handle "
		}
	]
}

Viewing drawing errors

See also: Sample Code: Find errors in a drawing

You can export your drawing to JSON to find errors with your drawing. Each view in the JSON includes an errorState for reporting drawing errors. See the Find dangling entities tutorial for an example.

Sample Code

Please see the Onshape TypeScript Drawing Client for a working example of using the Onshape Drawing APIs in an application.

Sample Workflows

Create a drawing from a part

In this example, we’ll create a drawing from the FLYWHEEL part in this public document.

  1. Create or open an Onshape document in which to create your drawing.
  2. Start to form the createDrawingAppElement call. Replace {did} and {wid} in the URL below with the document ID and workspace ID of your document (i.e., the target document), and replace CREDENTIAL with your authorization credentials.
    curl -X 'POST' \
  'https://cad.onshape.com/api/v6/drawings/d/{did}/w/{wid}/create' \
  -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' \
  3. Add the request body information:
    • Add flywheelDrawing as the drawingName field.
    • We must specify the source document’s document and version IDs. Note that since our target document and source document are different, we use the external document and version ID fields.
    • We must also provide the ID of the part to create the drawing from, and the ID of the element (i.e., tab) in which the part lives.
      (Hint: You can call getPartsWMVE to get a list of part IDs in an element.)
      curl -X 'POST' \
  'https://cad.onshape.com/api/v6/drawings/d/{did}/w/{wid}/create' \
  -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 '{
        "drawingName": "flywheelDrawing",
        "externalDocumentId": "e60c4803eaf2ac8be492c18e",
        "externalDocumentVersionId": "405ba186c3a70e0227ab2941", 
        "elementId": "6bed6b43463f6a46a37b4a22", 
        "partId": "JiD"
      }'
  4. Call the endpoint and open your document. Confirm that you see the new flywheelDrawing element containing the drawing:
    new drawing created from a part in an external document

Create a drawing from a template

In this example, we’ll create a drawing from the standard ANSI template in this public document.

  1. Open any Onshape document in which to create your drawing.
  2. Start to form the createDrawingAppElement call. Replace {did} and {wid} in the URL below with the document ID and workspace ID of your document (i.e., the target document), and replace CREDENTIAL with your authorization credentials.
    curl -X 'POST' \
  'https://cad.onshape.com/api/v6/drawings/d/{did}/w/{wid}/create' \
  -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' \
  3. Add the request body information:
    • Add templateAnsiDrawing as the drawingName field.
    • We must specify the source document’s document ID and workspace ID.
    • We must also provide the ID of the element (i.e., tab) in which the template lives.
    • Note that we use the template document, workspace, and element ID fields when referring to a specific template for drawing creation.
      curl 'https://cad.onshape.com/api/drawings/d/{did}/w/{wid}/create' \
  -H 'Authorization: Basic CREDENTIALS' \
  -H 'Accept: application/json, text/plain, */*' \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -d '{
    "drawingName": "templateAnsiDrawing",
    "templateDocumentId":"cbe6e776694549b5ba1a3e88",
    "templateWorkspaceId":"24d08acf10234dbc8d3ab585",
    "templateElementId":"17eef7862b224f6fb12cbc46"
    }'
  4. Call the endpoint and open your document. Confirm that you see the new templateAnsiDrawing element containing the empty drawing template.

Export a drawing to JSON

In this example, we’ll export a drawing from this public document to JSON. 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).

📘 Notes

  • Notes are exported with RTF15 formatting.
  • Flags are not currently exported with notes.
  • Geometric tolerance frame fields are separated with %%v.
  • Geometric tolerance prefix and suffix fields are currently not exported.

  1. Make a copy of this public document so you can export the drawing. Make a note of the documentId, workspaceId, and elementId of the drawing in your new document. These will be your {did}, {wid}, and {eid} fields for this example, unless otherwise specified.

  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.
    request

    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'

    response

    [
  {
    "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.
    • The formatName value must match the name field from the previous step exactly, including casing.

  4. In the reponse, copy the translationId value from the id field. This is the ID of the translation itself.

    {
  "requestState": "ACTIVE",
  "requestElementId": "{eid}",
  "resultExternalDataIds": null,
  "versionId": null,
  "workspaceId": "{wid}",
  "documentId": "{did}",
  "resultElementIds": null,
  "resultDocumentId": "{did}",
  "failureReason": null,
  "resultWorkspaceId": "{wid}",
  "name": "GEARBOX_CHUCK",
  "id": "{translationId}",
  "href": "https://cad.onshape.com/api/v9/translations/{translationId}"
}

  5. Next, poll the Translation/getTranslation response until requestState changes from ACTIVE to DONE or FAILED.

    {
  "requestState": "DONE",
  "requestElementId": "{eid}",
  "resultExternalDataIds": {resultElementId},
  "versionId": null,
  "workspaceId": "{wid}",
  "documentId": "{did}",
  "resultElementIds": {resultElementId},
  "resultDocumentId": "{did}",
  "failureReason": null,
  "resultWorkspaceId": "{wid}",
  "name": "GEARBOX_CHUCK",
  "id": "{translationId}",
  "href": "https://cad.onshape.com/api/v9/translations/{translationId}"
}

  6. Once requestState=DONE, the JSON is uploaded to the Onshape document in a new element (tab). The element ID of the JSON blob will either appear in the resultExternalDataIds or resultElementIds field in the response.

  7. 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/{resultElementId}' \
-H 'Authorization: Basic CREDENTIALS' \
  -H 'accept: application/octet-stream'
    • Use the {resultElementId} value from the translation response as the element ID. 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.

Create a drawing in a custom graphics area

  1. Open any Onshape document in which to create your drawing.
  2. Start to form the createDrawingAppElement call. Replace {did} and {wid} in the URL below with your document, and replace CREDENTIAL with your authorization credentials.
    curl -X 'POST' \
  'https://cad.onshape.com/api/v6/drawings/d/{did}/w/{wid}/create' \
  -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' \
  3. Add information about the drawings area. In this example, we’ll add an additional column and row to the drawings area, a title block, and add a border around it.
    curl -X 'POST' \
  'https://cad.onshape.com/api/v6/drawings/d/{did}/w/{wid}/create' \
  -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 '{
        "drawingName": "customGraphicsArea",
        "border": "true",
        "numberHorizontalZones": "3",
        "numberVerticalZones": "3"
        "titleblock": true
      }'
  4. Call the endpoint and open your document. Confirm that you see the new customGraphicsArea element:
    new drawing created with border and extra column and row

Add a note to a drawing

  1. Open an existing (or create a new) Onshape document with a drawing.
  2. Start to form the modifyDrawing call. Replace the URL parameters with the values from your document, and replace CREDENTIALS with your authorization credentials.
    curl -X 'POST \
  'https://cad.onshape.doc/api/v6/drawings/d/{did}/w/{wid}/e/{eid}/modify' \
  -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' \
  3. Add information about the modification. In this example, we’ll create an Onshape::Note on the drawing. We must specify the messageName and formatVersion for the modification, and then provide the contents and size of the annotation.
    curl -X 'POST \
  'https://cad.onshape.doc/api/v6/drawings/d/{did}/w/{wid}/e/{eid}/modify' \
  -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 '{
        "description": "Add a note to the drawing.",
        "jsonRequests": [ {
          "messageName": "onshapeCreateAnnotations",
          "formatVersion": "2021-01-01",
          "annotations": [
            {
              "type": "Onshape::Note",
              "note": {
                "position": {
                  "type": "Onshape::Reference::Point",
                  "coordinate": [
                    1,
                    10,
                    0
                  ]
                },
                "contents": "This is a note",
                "textHeight": 0.2
              }
            }
          ]  
        }]
      }'
  4. Make the call, and then get id from the response body. You’ll need this to poll the modification status to figure out when the modification has completed.
  5. Set up the getModificationStatus call. Replace {mrid} with the id from the last step, and replace CREDENTIALS with your credentials. Poll the modification status until the response returns "requestState": "DONE".
    curl -X 'GET \
  'https://cad.onshape.doc/api/v6/drawings/modify/status/{mrid}' \
  -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' \
  6. Open your drawing and confirm that you see the new note. Note that your drawing may not match this image exactly, depending on your drawing and document properties. This sample document uses Inches for units.
    drawing with note annotation

Add a callout to a drawing

  1. Open an existing (or create a new) Onshape document with a drawing.
  2. Start to form the modifyDrawing call. Replace the URL parameters with the values from your document, and replace CREDENTIALS with your authorization credentials.
    curl -X 'POST \
  'https://cad.onshape.doc/api/v6/drawings/d/{did}/w/{wid}/e/{eid}/modify' \
  -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' \
  3. Add information about the modification. In this example, we’ll add an Onshape::Callout to the drawing. We must specify the messageName and formatVersion for the modification, and then provide the contents and size of the annotation:
    curl -X 'POST \
  'https://cad.onshape.doc/api/v6/drawings/d/{did}/w/{wid}/e/{eid}/modify' \
  -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 '{
        "description": "Add a callout to the drawing.",
        "jsonRequests": [ {
          "messageName": "onshapeCreateAnnotations",
          "formatVersion": "2021-01-01",
          "annotations": [
            {
              "callout":
              {
                "borderShape": "Circle",
                "borderSize": 0,
                "contents": "Example Callout",
                "contentsBottom": "bottom",
                "contentsLeft": "left",
                "contentsRight": "right",
                "contentsTop": "top",
                "position": {
                  "coordinate": [
                    2.5,
                    6,
                    0
                  ],
                  "type": "Onshape::Reference::Point"
                },
                "textHeight": 0.12
              },
              "type": "Onshape::Callout"
            }
          ]  
        }]
      }'
  4. Make the call, and then get id from the response body. You’ll need this to poll the modification status to figure out when the modification has completed.
  5. Set up the getModificationStatus call. Replace {mrid} with the id from the last step, and replace CREDENTIALS with your credentials. Poll the modification status until the response returns "requestState": "DONE".
    curl -X 'GET \
  'https://cad.onshape.doc/api/v6/drawings/modify/status/{mrid}' \
  -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' \
  6. Open your drawing and confirm that you see the new callout.
    callout added to drawing

Add a centerline to a drawing

  1. Open an existing (or create a new) Onshape document with a drawing.
  2. Start to form the modifyDrawing call. Replace the URL parameters with the values from your document, and replace CREDENTIALS with your authorization credentials.
    curl -X 'POST \
  'https://cad.onshape.doc/api/v6/drawings/d/{did}/w/{wid}/e/{eid}/modify' \
  -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' \
  3. Add information about the modification. In this example, we’ll add an Onshape::Centerline to the drawing. We must specify the messageName and formatVersion for the modification, and then provide the coordinates of the centerline ends.
  • Note: you can Export a Drawing to JSON to get the coordinates, uniqueId and viewId values shown in the request below.
  • Note: if you have access, you can refer to the ODA documentation for more detailed formatting information.
    curl -X 'POST \
  'https://cad.onshape.doc/api/v6/drawings/d/{did}/w/{wid}/e/{eid}/modify' \
  -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 '{
        "description": "Add a centerline to the drawing",
        "jsonRequests": [ {
          "messageName": "onshapeCreateAnnotations",
          "formatVersion": "2021-01-01",
          "annotations": [
            {
              "pointToPointCenterline": {
                  "point1": {
                    "coordinate": [
                        2,
                        4,
                        0
                    ],
                    "type": "Onshape::Reference::Point",
                    "uniqueId": "point1",
                    "viewId": "51fa8b6040e411dfd17a4cda",
                    "snapPointType”: “ModeStart" 
                  },
                  "point2": {
                    "coordinate": [
                        7,
                        6,
                        1
                    ],
                    "type": "Onshape::Reference::Point",
                    "uniqueId": "point2",
                    "viewId": "51fa8b6040e411dfd17a4cda",
                    "snapPointType”: “ModeEnd" 
                  }
              },
              "type": "Onshape::Centerline::PointToPoint"
            }
          ]  
        }]
      }'
  1. Make the call, and then get id from the response body. You’ll need this to poll the modification status to figure out when the modification has completed.
  2. Set up the getModificationStatus call. Replace {mrid} with the id from the last step, and replace CREDENTIALS with your credentials. Poll the modification status until the response returns "requestState": "DONE".
    curl -X 'GET \
  'https://cad.onshape.doc/api/v6/drawings/modify/status/{mrid}' \
  -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' \
  3. Open your drawing and confirm that you see the new centerline.

Add a dimension to a drawing

  1. Open an existing (or create a new) Onshape document with a drawing.
  2. Start to form the modifyDrawing call. Replace the URL parameters with the values from your document, and replace CREDENTIALS with your authorization credentials.
    curl -X 'POST \
  'https://cad.onshape.doc/api/v6/drawings/d/{did}/w/{wid}/e/{eid}/modify' \
  -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' \
  3. Add information about the modification. In this example, we’ll add an Onshape::Dimension to the drawing. We must specify the messageName and formatVersion for the modification, and then provide the coordinates and formatting options for the dimension. (Hint: you can Export a Drawing to JSON to get a list of valid coordinates and handles.)
    curl -X 'POST \
  'https://cad.onshape.doc/api/v6/drawings/d/{did}/w/{wid}/e/{eid}/modify' \
  -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 '{
        "description": "Add a dimension to the drawing",
        "jsonRequests": [ {
          "messageName": "onshapeCreateAnnotations",
          "formatVersion": "2021-01-01",
          "annotations": [
            {
              "radialDimension": {
                "centerPoint": {
                  "coordinate": [
                    0.2800021171569824,
                    0.014964947476983043,
                    0.079502
                  ],
                  "type": "Onshape::Reference::Point",
                  "uniqueId": "point1",
                  "viewId": "e11c38795c04ca55047f7ea7",
                  "snapPointType”: “ModeCenter"
                },
                "chordPoint": {
                  "coordinate": [
                    0.2920149764955524,
                    0.010030535983985095,
                    0.079502
                  ],
                  "type": "Onshape::Reference::Point",
                  "uniqueId": "point2",
                  "viewId": "e11c38795c04ca55047f7ea7",
                  "snapPointType”: “ModeNear"
                },
                "formatting": {
                  "dimdec": 2,
                  "dimlim": false,
                  "dimpost": "R<>",
                  "dimtm": 0,
                  "dimtol": false,
                  "dimtp": 0,
                  "type": "Onshape::Formatting::Dimension"
                }
                "textOverride": "",
                "textPosition": {
                  "coordinate": [
                    191.80537349378181,
                    89.76274130852224,
                    0
                  ],
                  "type": "Onshape::Reference::Point"
                }
              },
              "type": "Onshape::Dimension::Radial"
            }
          ]  
        }]
      }'
  4. Make the call, and then get id from the response body. You’ll need this to poll the modification status to figure out when the modification has completed.
  5. Set up the getModificationStatus call. Replace {mrid} with the id from the last step, and replace CREDENTIALS with your credentials. Poll the modification status until the response returns "requestState": "DONE".
    curl -X 'GET \
  'https://cad.onshape.doc/api/v6/drawings/modify/status/{mrid}' \
  -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' \
  6. Open your drawing and confirm that you see the new dimension.

Add a geometric tolerance to a drawing

  1. Open an existing (or create a new) Onshape document with a drawing.
  2. Start to form the modifyDrawing call. Replace the URL parameters with the values from your document, and replace CREDENTIALS with your authorization credentials.
    curl -X 'POST \
  'https://cad.onshape.doc/api/v6/drawings/d/{did}/w/{wid}/e/{eid}/modify' \
  -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' \
  3. Add information about the modification. In this example, we’ll add an Onshape::GeometricTolerance to the drawing. We must specify the messageName and formatVersion for the modification, and then provide the frames and position of the annotation:
    curl -X 'POST \
  'https://cad.onshape.doc/api/v6/drawings/d/{did}/w/{wid}/e/{eid}/modify' \
  -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 '{
        "description": "Add a geometric tolerance to the drawing",
        "jsonRequests": [ {
          "messageName": "onshapeCreateAnnotations",
          "formatVersion": "2021-01-01",
          "annotations": [
            {
              "geometricTolerance": {
                "frames": [
                  "{\\fDrawing Symbols Sans;◎}%%v{\\fDrawing Symbols Sans;∅}tol1{\\fDrawing Symbols Sans;Ⓜ}%%v%%v%%v%%v%%v\n",
                  "{\\fDrawing Symbols Sans;⌖}%%vto2{\\fDrawing Symbols Sans;Ⓛ}%%v%%v%%v%%v%%v\n"
                ],
                "position": {
                  "coordinate": [
                    6,
                    6,
                    0
                  ],
                  "type": "Onshape::Reference::Point"
                }
              },
              "type": "Onshape::GeometricTolerance"
            }
          ]  
        }]
      }'
  4. Make the call, and then get id from the response body. You’ll need this to poll the modification status to figure out when the modification has completed.
  5. Set up the getModificationStatus call. Replace {mrid} with the id from the last step, and replace CREDENTIALS with your credentials. Poll the modification status until the response returns "requestState": "DONE".
    curl -X 'GET \
  'https://cad.onshape.doc/api/v6/drawings/modify/status/{mrid}' \
  -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' \
  6. Open your drawing and confirm that you see the new annotation.
    new drawing created with border and extra column and row

Add an inspection symbol to a drawing

  1. Open an existing (or create a new) Onshape document with a drawing.
  2. Start to form the modifyDrawing call. Replace the URL parameters with the values from your document, and replace CREDENTIALS with your authorization credentials.
    curl -X 'POST \
  'https://cad.onshape.doc/api/v6/drawings/d/{did}/w/{wid}/e/{eid}/modify' \
  -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' \
  3. Add information about the modification. In this example, we’ll add an Onshape::InspectionSymbol to the drawing. We must specify the messageName and formatVersion for the modification, and then provide the shape and position of the inspection symbol. (Hint: you can Export a Drawing to JSON to get a list of valid coordinates and handles.)
    curl -X 'POST \
  'https://cad.onshape.doc/api/v6/drawings/d/{did}/w/{wid}/e/{eid}/modify' \
  -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 '{
        "description": "Add an inspection symbol to the drawing",
        "jsonRequests": [ {
          "messageName": "onshapeCreateAnnotations",
          "formatVersion": "2021-01-01",
          "annotations": [
            {
              "inspectionSymbol": {
                "borderShape": "Circle",
                "borderSize": 2,
                "parentAnnotation": "h:10000577",
                "parentLineIndex": 0.0,
                "position": {
                  "coordinate": [
                    2.6,
                    6,
                    0
                  ],
                  "type": "Onshape::Reference::Point"
                },
                "textHeight": 2
              },
              "type": "Onshape::InspectionSymbol"
            }
          ]  
        }]
      }'
  4. Make the call, and then get id from the response body. You’ll need this to poll the modification status to figure out when the modification has completed.
  5. Set up the getModificationStatus call. Replace {mrid} with the id from the last step, and replace CREDENTIALS with your credentials. Poll the modification status until the response returns "requestState": "DONE".
    curl -X 'GET \
  'https://cad.onshape.doc/api/v6/drawings/modify/status/{mrid}' \
  -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' \
  6. Open your drawing and confirm that you see the new inspection symbol.

Add a table to a drawing

  1. Open an existing (or create a new) Onshape document with a drawing.
  2. Start to form the Drawings/modifyDrawing call. Replace the URL parameters with the values from your document, and replace CREDENTIALS with your authorization credentials.
    curl -X 'POST \
  'https://cad.onshape.doc/api/v6/drawings/d/{did}/w/{wid}/e/{eid}/modify' \
  -H 'Authorization: Basic CREDENTIALS' \s
  -H 'Accept: application/json;charset=UTF-8; qs=0.09' \
  -H 'Content-Type: application/json;charset=UTF-8; qs=0.09' \
  3. Add information about the modification. In this example, we’ll add an Onshape::Table::GeneralTable to the drawing. We must specify the messageName and formatVersion for the modification, and then provide the location, number of rows, and number of columns for the table. (Hint: you can Export a Drawing to JSON to get a list of valid coordinates.)
    curl -X 'POST \
  'https://cad.onshape.doc/api/v6/drawings/d/{did}/w/{wid}/e/{eid}/modify' \
  -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 '{
        "description": "New table",
        "jsonRequests": [ {
          "formatVersion": "2021-01-01",
          "messageName": "onshapeCreateAnnotations",
          "annotations": [
            { "table": {
                "cells": [
                  {
                    "column": 0,
                    "content": "1.1",
                    "row": 0
                  },
                  {
                    "column": 0,
                    "content": "2.1",
                    "row": 1
                  },
                  {
                    "column": 1,
                    "content": "1.2",
                    "row": 0
                  },
                  {
                    "column": 1,
                    "content": "2.2",
                    "row": 1
                  }
                ],
                "columns": 2,
                "rows": 2,
                "showHeaderRow": false,
                "showTitleRow": false,
                "position": {
                  "coordinate": [100.0, 400.0, 0.0],
                  "type": "Onshape::Reference::Point"
                }
              },
              "type": "Onshape::Table::GeneralTable"
            }]
        }]
      }'
  4. Make the call, and then get id from the response body. You’ll need this to poll the modification status to figure out when the modification has completed.
  5. Set up the getModificationStatus call. Replace {mrid} with the id from the last step, and replace CREDENTIALS with your credentials. Poll the modification status until the response returns "requestState": "DONE".
    curl -X 'GET \
  'https://cad.onshape.doc/api/v6/drawings/modify/status/{mrid}' \
  -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' \
  6. Open your drawing and confirm that you see the new table.

Specify a snap point

You can use the modifyDrawing to choose the snap points for annotations. Available types of snap points are:

 ModeApint       // Apparent intersection
 ModeCenter      // Center point
 ModeEnd         // End point
 ModeIns         // Insertion point
 ModeIntersec    // Intersection
 ModeMid         // Midpoint
 ModeNear        // Nearest point
 ModeNode        // Node
 ModePar         // Parallel
 ModePerp        // Perpendicular
 ModeQuad        // Quadrant
 ModeStart       // Start point
 ModeTan         // Tangent point
  1. Create a sketch in Onshape with two circles, then extrude both circles.
  2. Create a drawing of the part’s front view. We’ll use the Drawings API to a point to point centerline snapped to the centers of the holes.
    drawing front view of a box with two holes
  3. Next, we’ll need to get the view ID of the drawing. Call the Drawing/getDrawingViews_1 endpoint on your document to get a list of all views in the drawing, and copy the viewId from the response:
curl -X 'GET' \
  'https://cad.onshape.com/api/v8/drawings/d/{did}/w/{wid}/e/{eid}/views' \
  -H 'Authorization: Basic CREDENTIALS' \s
  -H 'accept: application/json;charset=UTF-8; qs=0.09' \
  -H 'Content-Type: application/json;charset=UTF-8; qs=0.09'
  1. Use the viewId from the last step to get the uniqueId (or edgeId) of each circle’s center from the Drawing/getDrawingViewJsonGeometry_1) endpoint:
curl -X 'GET' \
  'https://cad.onshape.com/api/v8/drawings/d/{did}/w/{wid}/e/{eid}/views/{viewId}/jsongeometry' \
  -H 'Authorization: Basic CREDENTIALS' \s
  -H 'accept: application/json;charset=UTF-8; qs=0.09' \
  1. Start to form the modifyDrawing call. Replace the URL parameters with the values from your document, and replace CREDENTIALS with your authorization credentials.
    curl -X 'POST \
  'https://cad.onshape.doc/api/v6/drawings/d/{did}/w/{wid}/e/{eid}/modify' \
  -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 { }
  2. Add information about the modification. In this example, we’ll add a pointToPointCenterline to the drawing. Make sure to update the request body values as followis:
  • messageName: "onshapeCreateAnnotation"
  • formatVersion: "2021-01-01"
  • uniqueId: From Step 4
  • viewId: From Step 3
  • coordinates: The values must be sent as part of the request, but are ignored.
        curl -X 'POST \
  'https://cad.onshape.doc/api/v8/drawings/d/{did}/w/{wid}/e/{eid}/modify' \
  -H 'Authorization: Basic CREDENTIALS' \s
  -H 'Accept: application/json;charset=UTF-8; qs=0.09' \
  -H 'Content-Type: application/json;charset=UTF-8; qs=0.09' \
  -d {
      "description": "creating a snap point",
      "jsonRequests": [ {
                "messageName": "onshapeCreateAnnotations",
                "formatVersion": "2021-01-01",
                "annotations": [
                  {
                    "pointToPointCenterline": {
                        "point1": {
                          "coordinate": [0,0,0],
                          "type": "Onshape::Reference::Point",
                          "uniqueId": "{uniqueId1}",
                          "viewId": "{viewId}",
                          "snapPointType": "ModeCenter"
                        },
                        "point2": {
                          "coordinate": [0,0,0],
                          "type": "Onshape::Reference::Point",
                          "uniqueId": "{uniqueId2}",
                          "viewId": "{viewId}",
                          "snapPointType": "ModeCenter"
                        }
                    },
                    "type": "Onshape::Centerline::PointToPoint"
                  }
                ]
              }]
      }
  1. Return to your document and see that the centerline has been added to the document at the snap points.
    drawing front view of a box with two holes with a centerline between the hole centers

Edit an annotation

You can edit an annotation using the Drawings/modifyDrawing API in the same way that you create an annotation. You’ll use the onshapeEditAnnotations message in place of onshapeCreateAnnotations, and you’ll need to supply the logicalId for the annotation. You must use the same type that you used to create the annotation.

Editing any annotation requires the following fields:

"messageName": "onshapeEditAnnotations"
"formatVersion": "2021-01-01"
"type": {see list below}
"logicalId": {logicalId}

The following types of annotations can be edited:

Onshape::Callout
Onshape::Note
Onshape::GeometricTolerance
Onshape::Centerline::PointToPoint
Onshape::Centerline::LineToLine
Onshape::Centerline::TwoPointCircular
Onshape::Centerline::ThreePointCircular
Onshape::Dimension::LineToLine
Onshape::Dimension::PointToPoint
Onshape::Dimension::PointToLine
Onshape::Dimension::Diametric
Onshape::Dimension::Radial
Onshape::Dimension::LineToLineAngular
Onshape::Dimension::ThreePointAngular
Onshape::InspectionSymbol

The example below walks through the steps for modifying a note:

  1. Open an existing (or create a new) Onshape document with a drawing that includes a note.
  2. Follow the steps for exporting a Drawing to JSON. In the JSON response, find the logicalId for the note you want to modify.
  3. Add your headers and the JSON body, including the required fields mentioned above, and the new text in the contents field.
    curl -X 'POST \
  'https://cad.onshape.doc/api/v6/drawings/d/{did}/w/{wid}/e/{eid}/modify' \
  -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 '{
        "description": "Update a note on a drawing.",
        "jsonRequests": [ {
          "messageName": "onshapeEditAnnotations",
          "formatVersion": "2021-01-01",
          "annotations": [
            {
              "type": "Onshape::Note",
              "note": {
                "contents": "This is new note text.",
                "logicalId": "{logicalId}"
              }
            }
          ]  
        }]
      }'
  4. Once the modification is done, open your drawing and confirm that you see the new text.

Find dangling entities

To identitfy dangling entities, you can export a drawing to JSON and search for any entities where isDangling is set to true.

  1. Make a copy of this public document so you can export the drawing. Make a note of the document ID, workspace ID, and element ID of the drawing in your new document. These will be your {did}, {wid}, and {eid} fields for this example, unless otherwise specified.

    Drawing with a dangling note and inspection symbol

    When this drawing was created, the drill bit part included a fillet. That fillet has since been deleted, so the attached note (This is a fillet) and inspection item (2) are now dangling. Since this is a simple drawing with only a few annotations, it is easy to visually identify the dangling entities. However, in large or complex drawings, it can be helpful to obtain a list of dangling entities from the JSON export.
  2. Use the createDrawingTranslation endpoint to export the drawing to JSON. See the Export a Drawing to JSON tutorial for help. Your call should look like this:
    curl -X 'POST' \
'https://cad.onshape.com/api/v10/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"
      }'
  3. Open the DRILL_BIT.json file from your document or by calling the BlobElement/downloadFileWorkspace endpoint on the new JSON element.
  4. In the JSON, search for the isDangling field. You’ll see that the first two annotations (This is a note and inspection symbol number: 1.0) are not dangling.
        {
        "note": {
            "contents": "{\\pxql;This is a note}",
            "isDangling": false,
            "logicalId": "h:100000EA",
            "position": {
                "coordinate": [
                    1.9878571202278066,
                    7.1981053727755056,
                    0.0
                ],
                "type": "Onshape::Reference::Point"
            },
            "textHeight": 0.12
        },
        "type": "Onshape::Note"
    },
    {
        "inspectionSymbol": {
            "borderShape": "Circle",
            "borderSize": 2.0,
            "isDangling": false,
            "itemParsing": "eByRow",
            "logicalId": "h:100000EB",
            "number": 1.0,
            "parentAnnotation": "h:100000EA",
            "parentLineIndex": 0,
            "position": {
                "coordinate": [
                    1.8438571202278065,
                    7.135399026040281,
                    0.0
                ],
                "type": "Onshape::Reference::Point"
            },
            "textHeight": 0.08
        },
        "type": "Onshape::InspectionSymbol"
    }

If you scroll further, however, you’ll see that the next set of annotations (This is a fillet and inspection symbol number: 2.0) have isDangling set to true. These annotations are dangling and must be corrected in the drawing.

  {
    "note": {
        "contents": "{\\pxqr;This is a fillet}",
        "isDangling": true,
        "leaderPosition": {
            "coordinate": [
                -0.0054142135623728715,
                0.24941421356237314,
                1.496198998029996e-17
            ],
            "snapPointType": "ModeMid",
            "type": "Onshape::Reference::Point",
            "uniqueId": "F426D",
            "viewId": "4868551da0b69cd0712723ae"
        },
        "logicalId": "h:100000EF",
        "position": {
            "coordinate": [
                2.995234893572328,
                6.3423785618475375,
                0.0
            ],
            "type": "Onshape::Reference::Point"
        },
        "textHeight": 0.12
    },
    "type": "Onshape::Note"
},
{
    "inspectionSymbol": {
        "borderShape": "Circle",
        "borderSize": 2.0,
        "isDangling": true,
        "itemParsing": "eByRow",
        "logicalId": "h:100000F7",
        "number": 2.0,
        "parentAnnotation": "h:100000EF",
        "parentLineIndex": 0,
        "position": {
            "coordinate": [
                1.8469297164606113,
                6.342509182410414,
                0.0
            ],
            "type": "Onshape::Reference::Point"
        },
        "textHeight": 0.08
    },
    "type": "Onshape::InspectionSymbol"
  }
  1. In the drawing, select the dangling note and inspection symbol, and press the delete key.
  2. Repeat steps 2 through 4 above for the updated drawing. Notice that all isDangling fields are now set to false.

📘 Note

Not all drawing objects support the isDangling field. If the isDangling field is not returned for an object or annotation in your drawing, no conclusions can be drawn from the API about the dangling status of the object.

Additional Resources