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
  • 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
    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
    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
    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.
  • createDrawingTranslation: See the Translations API Guide.
  • getDrawingTranslatorFormats: See the Translations API Guide.

Viewing drawing errors

You can export your drawing to a JSON to find errors with your drawing. Each view in the JSON includes an errorState for reporting drawing errors.

Sample App

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.

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 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 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"
                },
                "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"
                }
                "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.
  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::Diametric
  • Onshape::Dimension::Radial
  • Onshape::Dimension::LineToLineAngular
  • Onshape::Dimension::ThreePointAngular

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.

Additional Resources