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}, {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

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:

  • 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

  • Modify a drawing
    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.
  • Get the drawing modification status
    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.
  • Translate a drawing: See the Translations API Guide.
  • Get drawing translation formats: See the Translations API Guide.

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 Drawings/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 Part/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 Drawings/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 emtpy drawing template.

Create a drawing in a custom graphics area

  1. Open any Onshape document in which to create your drawing.
  2. Start to form the Drawings/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 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' \
  -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,
                "logicalId": "note1"
              }
            }
          ]  
        }]
      }'
  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 Drawings/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 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' \
  -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,
                "logicalId": "callout1"
              },
              "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 Drawings/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 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' \
  -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 a list of valid coordinates and handles.
  • 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"
                  },
                  "point2": {
                    "coordinate": [
                        7,
                        6,
                        1
                    ],
                    "type": "Onshape::Reference::Point",
                    "uniqueId": "point2",
                    "viewId": "ay6a8b6020e4h7dfdnn1499i"
                  }
              },
              "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 Drawings/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 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' \
  -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"
                },
                "chordPoint": {
                  "coordinate": [
                    0.2920149764955524,
                    0.010030535983985095,
                    0.079502
                  ],
                  "type": "Onshape::Reference::Point",
                  "uniqueId": "point2",
                  "viewId": "e11c38795c04ca55047f7ea7"
                },
                "formatting": {
                  "dimdec": 2,
                  "dimlim": false,
                  "dimpost": "R<>",
                  "dimtm": 0,
                  "dimtol": false,
                  "dimtp": 0,
                  "type": "Onshape::Formatting::Dimension"
                },
                "logicalId": "dimension1",
                "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 Drawings/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 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' \
  -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"
                ],
                "logicalId": "geometricTolerance1",
                "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 Drawings/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 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' \
  -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,
                "logicalId": "inspection1",
                "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 Drawings/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.

Additional Resources