Drawings

This page describes the APIs Onshape provides for working with Onshape drawings.

ℹ️ Onshape API Notes

  • All Onshape API calls must be properly authenticated.
  • For Enterprise accounts, replace cad in URLs with your company domain.
  • Onshape IDs are written as: {did}, {wvmid}, {eid}, {pid}, {otherId}. See Onshape API Intro for information on what these IDs mean and how to obtain them from your documents.
  • Variables for replacement are written as: {variable1} or <variableTwo>. Never include the braces or angle brackets themselves with these variables.
  • Visit the Learning Center's Intro to the Onshape API course for additional instruction and videos.

Sample Code

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.com/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": "string",
      "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.
    • The description field is limited to 32 characters.
  • 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.
    • The requestState field has three potential values:
      • ACTIVE: drawing modification is in progress
      • DONE: drawing modification finished successfully
      • FAILED: an error occurred and the drawing was not modified
    • To set up the call:
      • Replace {mrid} with the id returned in the modification response, and replace CREDENTIALS with your credentials.
      • Poll the modification status until the request is no longer ACTIVE.
      • POLL RESPONSIBLY. See Rate Limiting and API Limits for more information.
      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' \
  • 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

⚠️ WARNING

When polling for an operation to complete, use a reasonable interval (e.g., avoid polling multiple times a second, use an exponential backoff strategy, etc.). See Rate Limiting and API Limits for more information.

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 Succeeded and Some Failed | 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.

Examples - Create Drawings

Create a drawing

Endpoint

POST drawings/d/{did}/w/{wid}/create

Request Body

{
  "drawingName": "string",
  "elementId": "{sourceElementId}",
  "partId": "{partId}",
  "views": "one | four | suggested"
}

Notes

  • drawingName: Provide a name for the drawing element
  • elementId: Specify the elementId of the source Part Studio or assembly.
    • Be sure to use the target document information (the document to include the drawing in) in the path parameters and the source document information (the document that houses the part, Part Studio, or assembly to draw) in the request body.
    • externalDocumentId and externalDocumentVersionId (Optional): Provide the source document information to create a drawing from a Part Studio or assembly in another document.
  • partId: (Optional) Create a drawing of a specific part in a Part Studio. If not provided, the entire Part Studio is drawn.
  • views: Create one or four views, or allow Onshape to create suggested views.
    • If not specified, four views are created (Top, Right, Front, and Isometric).
    • If views = suggested, Onshape automatically picks the views to create based on MBD data, or creates four views if MBD data is not available.

Example

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

  1. 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/v17/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/v17/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",
        "views": "four"
      }'
  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 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/v17/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/v17/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 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 your document, and replace CREDENTIAL with your authorization credentials.
    curl -X 'POST' \
  'https://cad.onshape.com/api/v17/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/v17/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,
        "views": "zero"
      }'
  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

Examples - Add Annotations

Annotation types 

Onshape::BendNote
Onshape::Callout
Onshape::Centerline::PointToPoint
Onshape::Centerline::LineToLine
Onshape::Centerline::TwoPointCircleCenterline
Onshape::Centerline::ThreePointCircleCenterline
Onshape::Centermark
Onshape::Datum
Onshape::Dimension::ArcLength
Onshape::Dimension::Chamfer
Onshape::Dimension::Diametric
Onshape::Dimension::LineToLine
Onshape::Dimension::LineToLineAngular
Onshape::Dimension::Ordinate
Onshape::Dimension::PointToLine
Onshape::Dimension::PointToPoint
Onshape::Dimension::Radial
Onshape::Dimension::ThreePointAngular
Onshape::GeometricTolerance
Onshape::Hatch
Onshape::HoleCallout
Onshape::InspectionSymbol
Onshape::LinearPatternCentermark
Onshape::Note
Onshape::SurfaceFinishSymbol
Onshape::Table::BomTable
Onshape::Table::GeneralTable
Onshape::VirtualSharp

Add a note to a drawing

  1. Open an Onshape drawing. This example uses the drawing created in the Create a drawing from a part tutorial.
  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.com/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.com/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": "string",
        "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. Poll the modification status and wait for the modification to finish.
  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 Onshape drawing. This example uses the drawing created in the Create a drawing from a part tutorial.
  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.com/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.com/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": "string",
        "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. Poll the modification status and wait for the modification to finish.
  6. Open your drawing and confirm that you see the new callout.
    callout added to drawing

Add a hole callout to a drawing

Add a callout to a hole.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "messageName": "onshapeCreateAnnotations",
  "formatVersion": "2021-01-01",
  "annotations": [
    {
      "holeCallout": {
        "holeCountType": "Face_Excluding_Pattern",
        "leaderPosition": {
          "coordinate": [
            0.002,
            0.002,
            0.025
          ],
          "deterministicId": "{holeDeterministicId}",
          "snapPointType": "ModeCenter",
          "type": "Onshape::Reference::Point",
          "uniqueId": "{holeUniqueId}",
          "viewId": "{viewId}"
        },
        "textPosition": {
          "coordinate": [
            4.758,
            5.342,
            0
          ],
          "type": "Onshape::Reference::Point"
        },
        "unit": {
          "dualUnit": "Millimeter",
          "isDualUnitOverridden": false,
          "isUnitOverridden": false,
          "unit": "Inches"
        }
      },
      "type": "Onshape::HoleCallout"
    }
  ]
}

Notes

  • Call getDrawingViews on your drawing to get the viewId of the view in which the hole appears.
  • Call getDrawingViewJsonGeometry to get the uniqueId and deterministicId of the hole to add the callout to.
  • Supported holeCountType values: None, View, Face, Pattern, Part, Face_Excluding_Pattern.
  • To edit a hole callout, use the onshapeEditAnnotations message and provide the callout’s logicalId in the holeCallout block:
    {
  "messageName": "onshapeEditAnnotations",
  "formatVersion": "2021-01-01",
  "annotations": [
    {
      "holeCallout": {
        "logicalId": "h:10000F19",
        "prefix": "NewPrefix",
        "suffix": "NewSuffix"
      },
      "type": "Onshape::HoleCallout"
    }
  ]
}
  • Add a tapped depth tolerance to the callout by providing the following parameters in the holeCallout block:
    {
  "tappedDepth": {
    "isPrecisionOverridden": false,
    "precision": 3,
    "tolerance": {
      "isPrecisionOverridden": false,
      "lowerValue": 0.210,
      "precision": 3,
      "type": "Limits",
      "upperValue": 0.45
    },
    "value": 0.005
  }
}
  • Add text or symbols to the callout in the holeCallout block to provide metadata.

Add a centerline to a drawing

  1. Open an Onshape drawing. This example uses the drawing created in the Create a drawing from a part tutorial.
  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.com/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.com/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": "string",
        "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. Poll the modification status and wait for the modification to finish.
  3. Open your drawing and confirm that you see the new centerline.

Add a centerline between sketch arcs or circles

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Notes

  • Export a drawing to JSON to get the logicalId for the Onshape::Arc and/or Onshape::Circle references in the sketch.
  • Accepts lines, arcs and circles only; splines, notes and other centerlines are rejected.
  • rightExtensionLength extends the edge1 end; leftExtensionLength the edge2 end, in sheet units.
  • If a sketch curve is deleted, the centerline remains, but exports empty edge references, so that export cannot be sent back to recreate it.

Request Body - Create Creates a centerline between two sketch circles.

{
  "description": "string",
  "jsonRequests": [
    {
      "messageName": "onshapeCreateAnnotations",
      "formatVersion": "2021-01-01",
      "annotations": [
        {
          "type": "Onshape::Centerline::LineToLine",
          "lineToLineCenterline": {
            "edge1": {
              "type": "Onshape::Reference::Edge",
              "logicalId": <logicalIdEdgeOne>
            },
            "edge2": {
              "type": "Onshape::Reference::Edge",
              "logicalId": <logicalIdEdgeTwo>
            }
          }
        }
      ]
    }
  ]
}

Request Body - Edit Edits a centerline by extending both ends by 0.5 units.

{
  "description": "string",
  "jsonRequests": [
    {
      "messageName": "onshapeEditAnnotations",
      "formatVersion": "2021-01-01",
      "annotations": [
        {
          "type": "Onshape::Centerline::LineToLine",
          "lineToLineCenterline": {
            "logicalId": "h:10000096",
            "leftExtensionLength": 0.5,
            "rightExtensionLength": 0.5
          }
        }
      ]
    }
  ]
}

Add a geometric tolerance to a drawing

  1. Open an Onshape drawing. This example uses the drawing created in the Create a drawing from a part tutorial.
  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.com/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.com/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": "string",
        "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. Poll the modification status and wait for the modification to finish.
  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 Onshape drawing. This example uses the drawing created in the Create a drawing from a part tutorial.
  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.com/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.com/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": "string",
        "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. Poll the modification status and wait for the modification to finish.
  6. Open your drawing and confirm that you see the new inspection symbol.

Add a table to a drawing

  1. Open an Onshape drawing. This example uses the drawing created in the Create a drawing from a part tutorial.
  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.com/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.com/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": "string",
        "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. Poll the modification status and wait for the modification to finish.
  6. Open your drawing and confirm that you see the new table.

Add a datum to a drawing

  1. Open an Onshape drawing. This example uses the drawing created in the Create a drawing from a part tutorial.
  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.com/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 a datum block to the drawing. We must specify the messageName and formatVersion for the modification, and then provide the info for the datum. (Hint: you can Export a Drawing to JSON to get a list of valid coordinates for your datum’s position.)
    curl -X 'POST \
  'https://cad.onshape.com/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": "string",
        "jsonRequests": [ {
          "formatVersion": "2021-01-01",
          "messageName": "onshapeCreateAnnotations",
          "annotations": [
            { 
              "datum":{
                "arrowType": "DatumFilled", // DatumFilled | DatumBlank
                "contents": "A", // Replace with datum text
                "datumSize": 0.25, // Datum size
                "isDangling": false,
                "isDatumTarget": false,
                "logicalId":"h:100001DC",  // Datum ID
                "position": {  // Datum location
                  "coordinate":[
                    6.91,
                    3.24,
                    -1
                    ],
                  "type": "Onshape::Reference::Point"
                  },
                  "targetPosition": { // Datum arrow location
                    "coordinate": [
                      0.2,
                      0.2,
                      -0.1
                      ],
                    "snapPointType":"ModeNear",
                    "type":"Onshape::Reference::Point",
                    "uniqueId":"F4241", // Unique ID 
                    "viewId":"{viewId}" // View ID of the drawing
                  },
                  "textSize": 0.25 // Datum text size
                  },
                  "type":"Onshape::Datum"
            }]
        }]
      }'
  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. Poll the modification status and wait for the modification to finish.
  6. Open your drawing and confirm that you see the new datum.

Add a surface finish symbol to a drawing

This code adds a surface finish symbol (SFS) to a drawing in empty space.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "description": "string",
  "jsonRequests": [ {
    "messageName": "onshapeCreateAnnotations",
    "formatVersion": "2021-01-01",
    "annotations": [
      { 
        "surfaceFinishSymbol": { 
          "isAllAround": false, 
          "matRemovalAllowance": "", 
          "maxRoughness": "", 
          "maxRoughnessWidth": "", 
          "methodWaviness": "", 
          "minRoughness": "", 
          "position": { 
            "coordinate": [ 
              5.2, 
              5.7, 
              0 
            ], 
            "type": "Onshape::Reference::Point" 
          }, 
          "roughnessCutoff": "", 
          "surfaceDirectionLayType": "NotSpecified", 
          "surfaceTextType": "Basic", 
          "textHeight": 0.12 
          }, 
        "type": "Onshape::SurfaceFinishSymbol" 
      }
    ]
  }]
}

Add a surface finish symbol to an annotation

You can create a surface finish symbol (SFS) that’s attached to another annotation by supplying that annotation’s logical ID in the position.logicalId field. In this example, we create the SFS attached to a GDT.

To attach an SFS to a view edge, follow the instructions here: Associate an annotation with a view edge.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "description": "string",
  "jsonRequests": [ {
    "messageName": "onshapeCreateAnnotations",
    "formatVersion": "2021-01-01",
    "annotations": [
      { 
        "surfaceFinishSymbol": {
          "isAllAround": false,
          "isDangling": false,
          "matRemovalAllowance": "",
          "maxRoughness": "",
          "maxRoughnessWidth": "",
          "methodWaviness": "",
          "minRoughness": "",
          "position": {
            "coordinate": [
              7.8,
              3.5,
              0.0
            ],
            "logicalId": "{logicalId}",
            "type": "Onshape::Reference::Point"
          },
          "roughnessCutoff": "",
          "surfaceDirectionLayType": "PerpendicularToPlaneOfProjection",
          "surfaceTextType": "RemovalOfMaterialRequired",
          "textHeight": 0.0
        },
        "type": "Onshape::SurfaceFinishSymbol"
      }
    ]
  } ]
}

Add a centermark to a circular edge

You can Export a Drawing to JSON to get a list of valid coordinates and IDs for your drawing.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "description": "string",
  "jsonRequests": [ {  
    "messageName": "onshapeCreateAnnotations",  
    "formatVersion": "2021-01-01",  
    "annotations": [  
      {  
        "centermark": {  
          "bottomGripPoint": {  
            "coordinate": [  
              3.1822537578892087,  
              3.6563745010106074,  
              0.25000000000000008  
            ],  
            "type": "Onshape::Reference::Point"  
          },  
          "centerPoint": {  
            "coordinate": [  
              0.025104875729290184,  
              -2.7755575615628916e-17,  
              0.025400000000000007  
            ],  
            "snapPointType": "ModeCenter",  
            "type": "Onshape::Reference::Point",  
            "uniqueId": "{uniqueIdOfCenterPoint}",  
            "viewId": "{drawingViewId}"  
          },  
          "leftGripPoint": {  
            "coordinate": [  
              2.993828561038815,  
              3.8447996978610008,  
              0.25000000000000008  
            ],  
            "type": "Onshape::Reference::Point"  
          },
          "rightGripPoint": {  
            "coordinate": [  
              3.370678954739602,  
              3.8447996978610008,  
              0.25000000000000008  
            ],  
            "type": "Onshape::Reference::Point"  
            },  
          "topGripPoint": {  
            "coordinate": [  
              3.1822537578892087,  
              4.033224894711394,  
              0.25000000000000008  
            ],  
            "type": "Onshape::Reference::Point"  
          }  
        },  
        "type": "Onshape::Centermark"  
      }  
    ]  
  } ]
}

Add a centermark aligned with a view edge

You can Export a Drawing to JSON to get a list of valid coordinates and IDs for your drawing.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "description": "string",
  "jsonRequests": [ {  
    "messageName": "onshapeCreateAnnotations",  
    "formatVersion": "2021-01-01",  
    "annotations": [  
      {  
        "centermark": {  
          "alignEdge": {  
            "deterministicId": "{edgeDeterministicId}",  
            "type": "Onshape::Reference::Edge",
            "uniqueId": "{edgeUniqueId}",  
            "viewId": "{drawingViewId}"  
          },  
          "bottomGripPoint": {  
            "coordinate": [  
              2.8352194500430278,  
              3.245579835836262,  
              0.25000000000000008  
            ],  
            "type": "Onshape::Reference::Point"  
          },  
          "centerPoint": {  
            "coordinate": [  
              0,  
              -0.02296483610015257,  
              0.025400000000000007  
            ],  
            "snapPointType": "ModeCenter",  
            "type": "Onshape::Reference::Point",  
            "uniqueId": "{centerPointUniqueId}",  
            "viewId": "{drawingViewId}"  
          },  
          "leftGripPoint": {  
            "coordinate": [  
              2.5409071315113667,  
              3.2455798358362619,  
              0.25000000000000008  
            ],  
            "type": "Onshape::Reference::Point"  
          },  
          "rightGripPoint": {  
            "coordinate": [  
              2.8352194500430278,  
              3.539892154367923,  
              0.25000000000000008
            ],  
            "type": "Onshape::Reference::Point"  
          },  
          "topGripPoint": {  
            "coordinate": [  
              2.5409071315113667,  
              3.5398921543679227,  
              0.25000000000000008  
            ],  
            "type": "Onshape::Reference::Point"  
          }  
        },  
      "type": "Onshape::Centermark"  
      }  
    ]  
  } ]
}

Add a centermark with an extension line

You can set the length of extension lines by passing individual grip points or by passing
extensionLineLength. Export a Drawing to JSON to get a list of valid coordinates and IDs for your drawing.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "description": "string",
  "jsonRequests": [
    {  
      "messageName": "onshapeCreateAnnotations",  
      "formatVersion": "2021-01-01",  
      "annotations": [  
        {  
          "centermark": {  
            "centerPoint": {  
              "coordinate": [  
                0,  
                -0.02296483610015257,  
                0.025400000000000007  
              ],  
              "snapPointType": "ModeCenter",  
              "type": "Onshape::Reference::Point",  
              "uniqueId": "{centerPointUniqueId}",
              "viewId": "{drawingViewId}"  
            },  
            "extensionLineLength": 2  
          },  
          "type": "Onshape::Centermark"  
        }  
      ]  
    }  
  ]
}

Add a linear pattern centermark

Onshape::LinearPatternCentermark creates a row of centermarks on circular edges, joined by connecting lines. It accepts patterns made with the Centermark command and those generated automatically for a linear hole pattern (isAutomatic: true).

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Properties

  • circularEdges (required for creation) - Two or more circles defined as view edges or sketch circles.
  • showConnectingLines (optional) - Defaults to true on creation. Set to false to hide the connecting lines.
  • Returned in export only:
    • connectingLines
    • centermarks
    • isAutomatic
    • isHidden

Notes

  • Automatic patterns maintain their circles; only showConnectingLines can be changed.
  • A pattern hidden in its view is exported with isHidden: true and cannot be edited.
  • All circles must be in one view on one sheet; any circle already in another manual pattern, an isometric view, or a circle outside the crop boundary is refused.
  • When showConnectingLines: false, the existing lines are kept and still listed in the connectingLines export.
  • Export the drawing to JSON to get the viewId and uniqueId of the circularEdges.
  • Delete the pattern with onshapeDeleteEntities.

Request Body - Create

Creates a linear pattern centermark.

{
  "description": "string",
  "jsonRequests": [
    {
      "messageName": "onshapeCreateAnnotations",
      "formatVersion": "2021-01-01",
      "annotations": [
        {
          "type": "Onshape::LinearPatternCentermark",
          "linearPatternCentermark": {
            "circularEdges": [
              {
                "type": "Onshape::Reference::Edge",
                "viewId": <viewIdOne>,
                "uniqueId": <uniqueIdOne>
              },
              {
                "type": "Onshape::Reference::Edge",
                "viewId": <viewIdOne>,
                "uniqueId": <uniqueIdTwo>
              }
            ],
            "showConnectingLines": true
          }
        }
      ]
    }
  ]
}

Request Body - Edit

Adds a third hole and hides connecting lines.

{
  "description": "string",
  "jsonRequests": [
    {
      "messageName": "onshapeEditAnnotations",
      "formatVersion": "2021-01-01",
      "annotations": [
        {
          "type": "Onshape::LinearPatternCentermark",
          "linearPatternCentermark": {
            "logicalId": <logicalIdOne>,
            "circularEdges": [
              {
                "type": "Onshape::Reference::Edge",
                "viewId": <viewIdOne>,
                "uniqueId": <uniqueIdOne>
              },
              {
                "type": "Onshape::Reference::Edge",
                "viewId": <viewIdOne>,
                "uniqueId": <uniqueIdTwo>
              },
              {
                "type": "Onshape::Reference::Edge",
                "viewId": <viewIdOne>,
                "uniqueId": <uniqueIdThree>
              }
            ],
            "showConnectingLines": false
          }
        }
      ]
    }
  ]
}

Add and edit a BOM table

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "description": "string",
  "jsonRequests": [{
    "messageName": "onshapeCreateAnnotations",
    "formatVersion": "2021-01-01",
    "annotations": [
      {
        "bomTable": {
          "bomTableTemplate": "Follow assembly",
          "bomType": "Flattened",
          "formatting": {
            "fixedCorners": "FixedCornerTopRight",
            "flowDirection": "TtoB"
          },
          "position": {
            "coordinate": [
              9.33971874664118,
              7.378609056752285,
              0
            ],
            "type": "Onshape::Reference::Point"
          },
          "reference": {
            "documentId": <documentId>,
            "elementId": <elementId>
          }
        },
        "type": "Onshape::Table::BomTable"
      }
    ]
  }]
}

Notes

  • bomTableTemplate: (Required) Specify the template to use:
    • Follow assembly: (Default) Uses the template the assembly’s BOM uses.
    • Onshape Default BOM: Uses the Onshape default BOM template.
    • Any custom template name, set at the company level.
    • Template names are case insensitive.
    • Strings that do not match any valid template name are refused.
    • Alternatively, provide the template’s templateId instead of name.
  • bomType (Required) :
    • Flattened (default) | StructuredTopLevel | StructuredMultiLevel
    • Assembly-sourced BOMs only.
  • formatting (Required) : Set the location of the BOM table.
    • fixedCorners: FixedCornerNone (default) | FixedCornerTopLeft | FixedCornerTopRight | FixedCornerBottomLeft | FixedCornerBottomRight
    • flowDirection: TtoB (Top to bottom, default) | BtoT (Bottom to top)
  • position (Required) : Coordinate of the cell corner specified in the formatting block.
  • reference (Required) : The document and element IDs of the tab that houses the BOM to insert.
  • type (Required) : Must be Onshape::Table::BomTable for both creating and editing.
  • To edit a drawing BOM table:
  • cellOverrides[]: (Optional). Override the content in the BOM’s specified cell.
    • row:
      • The row of the cell to replace.
      • First data row is 0.
      • Header row is not counted.
    • column:
      • The column of the cell to replace.
      • First column is 0.
    • content: The text to put in the current cell.
    • isContentOverridden:
      • true to override the specified cell with the string in the content field.
      • false to go back to the BOM’s original value.
    • isBold: true | false
    • alignment.alignment: How to align the text within the cell. Allowed values are:
      "kTopLeft",     "kTopCenter",     "kTopRight"
"kMiddleLeft",  "kMiddleCenter",  "kMiddleRight"
"kBottomLeft",  "kBottomCenter",  "kBottomRight"
    • Cell override example:
      "cellOverrides": [
  { "row": 0, "column": 1, "content": "Custom text", "isContentOverridden": true, "isBold": true, 
    "alignment": { "alignment": "kMiddleLeft" }
  }]

Add and edit a hatch

Add a hatch on a drawing sheet or inside a view. Specify the region to hatch with an interior seedPoint, by the sketch entities that bound it (boundaryEntities), or both.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Properties

  • One of seedPoint and boundaryEntities is required:
    • seedPoint
      • Hatches inside a view must use a seedPoint.
      • If inside a view, provide the viewId and the view’s model coordinate array.
      • If on the sheet, provide the sheet’s coordinate array.
    • boundaryEntities
      • Specify the logicalId of each entity.
      • Accepts sketch entities on the sheet, not view edges.
  • Style properties are optional and match the Hatch region dialog:
    • pattern: Solid, ANSI, ISO and General patterns.
    • scale: Defaults to 1.
    • angle: Defaults to 0 degrees.
    • Use isPatternOverridden and isColorOverridden to follow (false) or override (true) drawing-wide settings.
  • viewId, patternCategory: Read-only, available on export.

Notes

  • Use messageName: onshapeEditAnnotations and the hatch’s logicalId to edit a hatch region.
  • The hatch’s boundary cannot be edited; to change the region, delete the hatch and create it again.
  • Only one region per hatch is allowed: a boundary that encloses several regions without a seed point (or a seed point in an already hatched region) are rejected.
  • A pattern too dense for its scale is rejected on both create and edit.
  • Export the drawing to JSON to get the logical IDs and coordinates needed.
  • Delete the hatch with onshapeDeleteEntities.

Request Body - Create

Creates a hatch between two sketch circles.

{
  "description": "string",
  "jsonRequests": [
    {
      "messageName": "onshapeCreateAnnotations",
      "formatVersion": "2021-01-01",
      "annotations": [
        {
          "type": "Onshape::Hatch",
          "hatch": {
            "pattern": "ANSI31", // See the Hatch dialog for supported patterns.
            "seedPoint": {
              "type": "Onshape::Reference::Point",
              "coordinate": [
                20.75,
                6.75,
                0
              ]
            },
            "boundaryEntities": [
              <logicalIdEntityOne>,
              <logicalIdEntityTwo>
            ]
          }
        },
        {
          "type": "Onshape::Hatch",
          "hatch": {
            "pattern": "ANSI31", // See the Hatch dialog for supported patterns.
            "seedPoint": {
              "type": "Onshape::Reference::Point",
              "viewId": <viewId>,
              "coordinate": [
                0.0127,
                0.0127,
                0.0127
              ]
            }
          }
        }
      ]
    }
  ]
}

Request Body - Edit

Edits the two hatch regions.

{
  "description": "string",
  "jsonRequests": [
    {
      "messageName": "onshapeEditAnnotations",
      "formatVersion": "2021-01-01",
      "annotations": [
        {
          "type": "Onshape::Hatch",
          "hatch": {
            "logicalId": <logicalIdHatchOne>,
            "pattern": "ANSI31", // See the Hatch dialog for supported patterns.
            "isPatternOverridden": true,
            "scale": 2,
            "angle": 45
          }
        },
        {
          "type": "Onshape::Hatch",
          "hatch": {
            "logicalId": <logicalIdHatchTwo>,
            "isColorOverridden": true,
            "color": {
              "colorType": "byColor",
              "red": 255,
              "green": 0,
              "blue": 0
            }
          }
        }
      ]
    }
  ]
}

Add a virtual sharp

A virtual sharp marks the point where two straight edges meet (or where their extensions would meet).

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Notes

  • The edges can be:
    • Two view edges (specified with viewId and either uniqueId or deterministicId)
    • Two sketch lines on the sheet (specified with logicalId).
    • One of each.
  • Accepts straight, non-parallel edges only.
  • Both edges must be on the sheet of the virtual sharp;
  • Edges from two different views on the same sheet are accepted.
  • The virtual sharp point is computed and exported as a position
    • position is always recalculated; any value sent in the payload is ignored.
  • Display settings (e.g., centermark or edge extension, line weight, color) are drawing-wide and not part of the payload.
  • Export the drawing to JSON to get the IDs of the references.
  • Delete the annotation with onshapeDeleteEntities.

Request Body - Create

Creates one virtual sharp on two view edges and one on two sketch lines.

{
  "description": "string",
  "jsonRequests": [
    {
      "messageName": "onshapeCreateAnnotations",
      "formatVersion": "2021-01-01",
      "annotations": [
        {
          "type": "Onshape::VirtualSharp",
          "virtualSharp": {
            "edge1": {
              "type": "Onshape::Reference::Edge",
              "uniqueId": <uniqueIdEdgeOne>,
              "viewId": <viewIdOne>
            },
            "edge2": {
              "type": "Onshape::Reference::Edge",
              "uniqueId": <uniqueIdEdgeTwo>,
              "viewId": <viewIdOne>
            }
          }
        },
        {
          "type": "Onshape::VirtualSharp",
          "virtualSharp": {
            "edge1": {
              "type": "Onshape::Reference::Edge",
              "logicalId": <logicalIdEdgeOne>
            },
            "edge2": {
              "type": "Onshape::Reference::Edge",
              "logicalId": <logicalIdEdgeTwo>
            }
          }
        }
      ]
    }
  ]
}

Request Body - Edit

Changes a virtual sharp’s edge.

{
  "description": "string",
  "jsonRequests": [
    {
      "messageName": "onshapeEditAnnotations",
      "formatVersion": "2021-01-01",
      "annotations": [
        {
          "type": "Onshape::VirtualSharp",
          "virtualSharp": {
            "logicalId": <logicalIdVSharpOne>,
            "edge1": {
              "type": "Onshape::Reference::Edge",
              "uniqueId": <uniqueIdEdgeOne>,
              "viewId": <viewIdOne>
            }
          }
        }
      ]
    }
  ]
}

Examples - Edit Annotations

See Annotation types.

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.

ℹ️ NOTE

You can create a logicalId alias when you create an annotation, and refer to that alias in other drawing modifications. Currently, these aliases are not returned in a drawing export.

For example, if you send "logicalId": "myDrawingNote" as part of the request when creating a note annotation, you can later use logicalId=myDrawingNote when editing the annotation.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "description": "string",
  "jsonRequests": [ {
    "messageName": "onshapeEditAnnotations",
    "formatVersion": "2021-01-01",
    "annotations": [
      {
        "type": "{see Type list below}",
        "note": {
          "contents": "This is new note text.",
          "logicalId": "{logicalId}"
        }
      }
    ]  
  }]
}

Example

  1. Open an Onshape drawing. This example uses the drawing created in the Create a drawing from a part tutorial.
  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.com/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": "string",
        "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.

Attach an annotation to a parent

To attach an annotation to a parent, you can send the parentAnnotation field in your request body. The new annotation’s position must still be provided. The position determines where the annotation is placed, while the parentAnnotation determines when the annotation moves; an annotation that isn’t attached to a parent can be moved freely. An annotation attached to a parent moves when the parent annotation moves.

This example request body creates a geometric tolerance annotation attached to a parent annotation with logical ID h:100000B1.

ℹ️ NOTE

Surface finish symbols behave differently. See Add a SFS to an annotation for steps.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "description": "string",
  "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"
          ],
          "parentAnnotation": "h:100000B1",
          "position": {
            "coordinate": [
              6,
              6,
              0
            ],
            "type": "Onshape::Reference::Point"
          }
        },
        "type": "Onshape::GeometricTolerance"
      }
    ]  
  }]
}

Modify an annotation on a non-active sheet

Create or edit an annotation in a non-active drawing sheet by providing at least one parameter in the sheetDetails block. Export a drawing to JSON to find its index, logicalId or name.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "sheetDetails": {  
    "index": 2,
    "logicalId": "h:1000037D",
    "name": "Drawing 1"
  }
}

Example

Create an annotation on a non-active sheet:

{
  "messageName": "onshapeCreateAnnotations",
  "formatVersion": "2021-01-01",
  "sheetDetails": {
    "index": 2,
    "logicalId": "h:1000037D",
    "name": "Drawing 1"
    },  
  "annotations": [  
    {  
    "note": {  
      "contents": "{\\pxql;NoteOne}",  
      "position": {  
        "coordinate": [  
          360.91028080282219,  
          328.9839912941027,  
          0  
          ],  
        "type": "Onshape::Reference::Point"  
        },  
      "textHeight": 10.5  
      },  
    "type": "Onshape::Note"  
    }
  ]
}

Edit an annotation on a non-active sheet:

{  
  "messageName": "onshapeEditAnnotations",  
  "formatVersion": "2021-01-01",  
  "sheetDetails": {  
    "index": 2,  
    "logicalId": "h:1000013C",  
    "name": "Sheet2"  
    },  
  "annotations": [  
    {  
      "note": {  
        "contents": "TestNote1",  
        "logicalId": "h:100002CB",  
        "position": {  
          "coordinate": [  
            5,  
            4,  
            0
            ],  
          "type": "Onshape::Reference::Point"  
          },  
        "textHeight": 0.12  
        },  
      "type": "Onshape::Note"  
    }  
  ]  
}

Associate a leader with a view edge

Add the leaderPosition object to your request body to create a leader associated with a view edge.

{
  "leaderPosition": {
    "coordinate": [
      0.1,
      5.6,
      0.1
    ],
    "deterministicId": "{deterministicId}",
    "snapPointType": "ModeMid",
    "type": "Onshape::Reference::Point",
    "uniqueId": "{uniqueId}",
    "viewId": "{viewId}"
  }
}
annotation leader associated with a view edge

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "description": "string",
  "jsonRequests": [ {
    "messageName": "onshapeCreateAnnotations",
    "formatVersion": "2021-01-01",
    "annotations": [
      {
        "geometricTolerance": {
          "frames": [
            "{\\fDrawing Symbols Sans;◎}%%v{\\fDrawing Symbols Sans;∅}tol1{\\fDrawing Symbols Sans;:m:}%%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"
          },
          "leaderPosition": {
            "coordinate": [
              0.1,
              5.6,
              0.1
            ],
            "deterministicId": "{deterministicId}",
            "snapPointType": "ModeMid",
            "type": "Onshape::Reference::Point",
            "uniqueId": "{uniqueId}",
            "viewId": "{viewId}"
          }
        },
        "type": "Onshape::GeometricTolerance"
      }
    ]
  }]
}

Workflow

  1. Call getDrawingViews on your drawing to get the viewId of the view to add the annotation to.
  2. Call getDrawingViewJsonGeometry to get the uniqueId and deterministicId of the edge to add the annotation to.
  3. Call modifyDrawing with the request body shown above to create the annotation.

Associate an annotation with a view edge without a leader

Add the following information to the annotation’s position object to associate the annotation with a view edge:

{
  "deterministicId": "{deterministicId}",
  "snapPointType": "ModeNear",
  "type": "Onshape::Reference::Point",
  "uniqueId": "{uniqueId}",
  "viewId": "{viewId}"
}
annotation associated with a view edge without a leader

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "description": "string",
  "jsonRequests": [ {
    "messageName": "onshapeCreateAnnotations",
    "formatVersion": "2021-01-01",
    "annotations": [
      {
        "geometricTolerance": {
          "frames": [
            "{\\fDrawing Symbols Sans;◎}%%v{\\fDrawing Symbols Sans;∅}tol1{\\fDrawing Symbols Sans;:m:}%%v%%v%%v%%v%%v\n",
            "{\\fDrawing Symbols Sans;⌖}%%vto2{\\fDrawing Symbols Sans;Ⓛ}%%v%%v%%v%%v%%v\n"
          ],
          "position": {
            "coordinate": [
              0.05703643988890697,
              -0.04311684802152582,
              0.025400000000000004
            ],
            "deterministicId": "{deterministicId}",
            "snapPointType": "ModeNear",
            "type": "Onshape::Reference::Point",
            "uniqueId": "{uniqueId}",
            "viewId": "{viewId}"
          }
        },
        "type": "Onshape::GeometricTolerance"
      }
    ]
  }]
}

Workflow

  1. Call getDrawingViews on your drawing to get the viewId of the view to add the annotation to.
  2. Call getDrawingViewJsonGeometry to get the uniqueId and deterministicId of the edge to add the annotation to.
  3. Call modifyDrawing with the request body shown above to create the annotation.

Specify a snap point

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

snapPointType values

 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.com/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 follows:
  • 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.com/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": "string",
      "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

Reassociate a centermark with a new edge

You can change the associated edge of a centermark. Export a Drawing to JSON to get a list of valid coordinates and IDs for your drawing.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "description": "string",
  "jsonRequests": [
    {  
      "messageName": "onshapeEditAnnotations",  
      "formatVersion": "2021-01-01",  
      "annotations": [  
        {  
          "centermark": {  
            "centerPoint": {
              "coordinate": [  
                0.025104875729290184,  
                -2.7755575615628916e-17,  
                0.025400000000000007  
              ],  
              "snapPointType": "ModeCenter",  
              "type": "Onshape::Reference::Point",  
              "uniqueId": "{newEdgeUniqueId}",  
              "viewId": "{drawingViewId}"  
            },  
            "logicalId": "{centermarkLogicalId}"  
          },
          "type": "Onshape::Centermark"  
        }]  
    }]
}

Move a bend note

An Onshape::BendNote is the note Onshape places on each bend line of a sheet-metal flat pattern view, such as "UP 90.0° R.200". Bend notes are created with the view, so the API exports them and edits their two grips: position (text center, sheet coordinates) and attachmentPoint (on the bend line, view model coordinates).

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Notes

  • Export a Drawing to JSON to get the logicalId of the bend note to edit.
  • A create request for Onshape::BendNote is rejected.
  • Bend notes cannot be deleted.
    • In an onshapeDeleteEntities request, a bend note fails with Cannot delete bend note; the other entities in the request are still deleted.
    • To hide bend notes, turn them off on the view.
  • Read-only properties are returned during export but ignored if sent on edit:
    • bendLineText
    • direction
    • angle
    • radius
  • The attachment point must be on the note’s own bend line; a note cannot move to another bend line.
  • Bend notes of a view with showBendNotes: false are not exported.

Request Body - Edit Moves the bend note text.

{
  "description": "string",
  "jsonRequests": [
    {
      "messageName": "onshapeEditAnnotations",
      "formatVersion": "2021-01-01",
      "annotations": [
        {
          "type": "Onshape::BendNote",
          "bendNote": {
            "logicalId": <logicalIdBendNoteOne>,
            "position": {
              "type": "Onshape::Reference::Point",
              "coordinate": [
                3.4,
                7.6,
                0
              ]
            }
          }
        }
      ]
    }
  ]
}

Exported JSON (trimmed)

{
  "type": "Onshape::BendNote",
  "bendNote": {
    "logicalId": "h:100000B9",
    "position": {
      "type": "Onshape::Reference::Point",
      "coordinate": [
        3.19,
        5.7212,
        0
      ]
    },
    "attachmentPoint": {
      "type": "Onshape::Reference::Point",
      "viewId": "98d660c66d884cf1db9d187f",
      "uniqueId": "F4241",
      "coordinate": [
        0,
        -0.0619,
        0
      ]
    },
    "bendLineText": "UP 90.0° R.200",
    "direction": "Up",
    "angle": 90,
    "radius": 0.2,
    "isDangling": false
  }
}

Examples - Sketches

Sketch types

Onshape::Arc
Onshape::Circle
Onshape::Line
Onshape::SketchPoint
Onshape::Spline

Sketch a circle

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "description": "string",
  "jsonRequests": [ {
    "messageName": "onshapeCreateAnnotations",
    "formatVersion": "2021-01-01",
    "annotations": [
      {
        "circle": {
          "center": {
            "coordinate": [
              6.9,
              6.1,
              0
            ],
            "type": "Onshape::Reference::Point"
          },
          "radius": 1.0
        },
        "type": "Onshape::Circle"
      }]
  }]
}

Sketch a three-point circle

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "description": "string",
  "jsonRequests": [ {
    "messageName": "onshapeCreateAnnotations",
    "formatVersion": "2021-01-01",
    "annotations": [
      {
        "circle": {
          "point1": {
            "coordinate": [
              8.5,
              6.2,
              0
            ],
            "type": "Onshape::Reference::Point"
          },
          "point2": {
            "coordinate": [
              9.2,
              6.2,
              0
            ],
            "type": "Onshape::Reference::Point"
          },
          "point3": {
            "coordinate": [
              8.9,
              5.6,
              0
            ],
            "type": "Onshape::Reference::Point"
          }
        },
        "type": "Onshape::Circle"
      }]
  }]
}

Sketch a line

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "description": "string",
  "jsonRequests": [ {
    "messageName": "onshapeCreateAnnotations",
    "formatVersion": "2021-01-01",
    "annotations": [
      {
        "line": {
          "endPoint": {
            "coordinate": [
              6.1,
              4.7,
              0
            ],
            "type": "Onshape::Reference::Point"
          },
          "startPoint": {
            "coordinate": [
              6.1,
              3.6,
              0
            ],
            "type": "Onshape::Reference::Point"
          }
        },
        "type": "Onshape::Line"
      }]
  }]
}

Sketch an arc

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "description": "string",
  "jsonRequests": [ {
    "messageName": "onshapeCreateAnnotations",
    "formatVersion": "2021-01-01",
    "annotations": [
      {
        "arc": {
          "center": {
            "coordinate": [
              1.7,
              1.8,
              0
            ],
            "type": "Onshape::Reference::Point"
          },
          "endAngle": 5.9,
          "radius": 0.5,
          "startAngle": 2.4
        },
        "type": "Onshape::Arc"
      }]
  }]
}

Sketch a spline

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "description": "string",
  "jsonRequests": [ {
    "messageName": "onshapeCreateAnnotations",
    "formatVersion": "2021-01-01",
    "annotations": [
      {
        "spline": {
          "points": [
            {
              "coordinate": [
                9.3,
                3.5,
                0
              ],
              "type": "Onshape::Reference::Point"
            },
            {
              "coordinate": [
                9.8,
                4.3,
                0
              ],
              "type": "Onshape::Reference::Point"
            },
            {
              "coordinate": [
                10.4,
                4.9,
                0
              ],
              "type": "Onshape::Reference::Point"
            },
            {
              "coordinate": [
                10.3,
                5.8,
                0
              ],
              "type": "Onshape::Reference::Point"
            }
          ]
        },
        "type": "Onshape::Spline"
      }]
  }]
}

Create a sketch point

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "description": "string",
  "jsonRequests": [ {
    "messageName": "onshapeCreateAnnotations",
    "formatVersion": "2021-01-01",
    "annotations": [
      {
        "sketchPoint": {
          "position": {
            "coordinate": [
              5.7,
              2.3,
              0
            ],
            "type": "Onshape::Reference::Point"
          }
        },
        "type": "Onshape::SketchPoint"
      }]
  }]
}

Create a sketch grouped with a view

Specify the viewId field and type in the sketch object (e.g., circle, line, arc, etc.)

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "description": "string",
  "jsonRequests": [ {
    "messageName": "onshapeCreateAnnotations",
    "formatVersion": "2021-01-01",
    "annotations": [
      {
        "circle": {
          "center": {
            "coordinate": [
              6.9,
              6.1,
              0
            ],
            "type": "Onshape::Reference::Point"
          },
          "radius": 1.0,
          "viewId": "{viewId}"
        },
        "type": "Onshape::Circle"
      }]
  }]
}

Edit a sketch

Specify the properties to edit in the sketch object (e.g., circle, line, arc, etc.) for the given sketch’s logical ID. The following example edits the center coordinate for an arc.

{
  "description": "string",
  "jsonRequests": [ {
    "messageName": "onshapeEditAnnotations",
    "formatVersion": "2021-01-01",
    "annotations": [
      {
        "arc": {
          "center": {
            "coordinate": [
              1.7,
              1.8,
              0
            ],
            "type": "Onshape::Reference::Point"
          },
          "endAngle": 5.9,
          "logicalId": "{logicalId}",
          "radius": 0.5,
          "startAngle": 2.4,
          "viewId": "{viewId}"
        },
        "type": "Onshape::Arc"
      }]
  }]
}

Edit a spline point

Specify both the logical ID of the spline and the spline point.

{
	"description": "string",
	"jsonRequests": [
		{
			"description": "string",
			"formatVersion": "2021-01-01",
			"messageName": "onshapeEditAnnotations",
			"annotations": [
				{
					"splinePoint": {
						"logicalId": "h:100000B0",
						"position": {
							"coordinate": [
								10.528444592617669,
								11.822459335116016,
								0
							],
							"type": "Onshape::Reference::Point"
						},
						"splineLogicalId": "h:100000AE"
					},
					"type": "Onshape::SplinePoint"
				}
			]
		}
	]
}

Examples - Views

ℹ️ NOTE

See supported fields in our sample code.

Currently, only TopLevel, Projected, Section, and Auxiliary view types are supported for creating and editing via the Onshape API. Other view types listed are available for export only.

Add a view

The code below adds a view of a part to a drawing.

  • Call getPartsWMVE to get a list of part IDs in an element.
  • Remove the idTag field from the request body to specify a Part Studio or assembly view.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "description": "string",
  "jsonRequests": [ 
    {
    "messageName": "onshapeCreateViews",
    "formatVersion": "2021-01-01",
    "description": "string",
    "views": [
        {
          "viewType": "TopLevel",
          "position": {"x": 7,"y": 6},
          "scale": {"scaleSource": "Custom", "numerator": 3, "denumerator": 1},
          "orientation": "front",
          "reference": {
            "elementId": "{partStudioOrAssemblyElementId}",
            "idTag": "{partId}"
          }
        }]
    }]
}

Add projected views

The code below adds three views as children of the view created in the last example. Export a Drawing to JSON to obtain the logicalId of the parent view.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "description": "string",
  "jsonRequests": [ 
    {
    "messageName": "onshapeCreateViews",
    "formatVersion": "2021-01-01",
    "description": "string",
    "views": [
        {
            "viewType": "Projected",
            "position": {"x": 16,"y":6},
            "parentView": {"logicalId" : "{parentViewLogicalId}"},
            "name": "ChangedViewName",
            "showViewLabel": true
        },
        {
            "viewType": "Projected",
            "position": {"x": 7,"y":13},
            "parentView": {"logicalId" : "{parentViewLogicalId}"},
            "showShadedView": true,
            "showCentermarks": false
        },
        {
            "viewType": "Projected",
            "position": {"x": 16,"y":13},
            "parentView": {"logicalId" : "{parentViewLogicalId}"},
            "scale": {"scaleSource": "Custom", "numerator": 2, "denumerator": 1},
            "showHiddenLines": true
        }]
    }]
}

Add or edit a section view

See Onshape Help - Drawing Section Views.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body - Create with required params only

{
  "description": "string",
  "jsonRequests": [ 
    {
    "messageName": "onshapeCreateViews",
    "formatVersion": "2021-01-01",
    "description": "string",
    "views": [
      {
      "attachmentPoints": [
        {
          "coordinate": [
            -0.015,
            0.038,
            0.025
          ],
          "deterministicId": <pointOneDeterministicId>,
          "snapPointType": <snapPointOneType>,
          "type": "Onshape::Reference::Point",
          "uniqueId": <pointOneUniqueId>,
          "viewId": <viewId>
        },
        {
          "coordinate": [
            0.009,
            -0.038,
            0.0254
          ],
          "deterministicId": <pointTwoDeterministicId>,
          "snapPointType": <snapPointTwoType>,
          "type": "Onshape::Reference::Point",
          "uniqueId": <pointTwoUniqueId>,
          "viewId": <viewId>
        }
      ],
      "parentViewId": <viewId>,
      "position": {
        "x": 5.393,
        "y": 5.175
      },
      "sectionType": "Vertical", // Vertical | Horizontal | Angular
      "viewType": "Section"
    }]
  }]
}

Request Body - Edit optional params

{
  "description": "string",
  "jsonRequests": [ 
    {
    "messageName": "onshapeEditViews",
    "formatVersion": "2021-01-01",
    "description": "string",
    "views": [
      {
        "logicalId": <sectionViewLogicalId>, // ID of section view to edit
        "attachmentPoints": [
        {
          "coordinate": [
            -0.05343566999025993,
            -0.02712734094000123,
            0.02521309820980810
          ],
          "deterministicId": <pointThreeDeterministicId>,
          "snapPointType": <pointThreeSnapType>,
          "type": "Onshape::Reference::Point",
          "uniqueId": <pointThreeUniqueId>,
          "viewId": <pointThreeViewId>
        }],
        "cutAngle": -45, // Positive values are clockwise. Negative values are counter-clockwise.
        "cutFromSection": false,
        "isCutAngleEnabled": true,
        "joggedSectionLinePoints": [
          {
            "coordinate": [
              4.26843566999025993,
              6.89149801275942033,
              0.25001535815000534
            ],
            "type": "Onshape::Reference::Point"
          },
          {
            "coordinate": [
              6.893000012221000006,
              4.266000001000000006,
              0.250000004600000343
            ],
            "type": "Onshape::Reference::Point"
          }
        ],
        "labelDefinition": {
          "letter": "A",
          "prefix": "SECTION",
          "suffix": ""
        },
        "position": {
          "x": 8.86400000000000223,
          "y": 8.68700000000000006
        },
        "sectionDepth":
        {
          "endType": "UptoEntity", // Must be UptoEntity or Blind
          "sectionDepthPoint": {
            "coordinate": [
              0,
              -0.010458248197463549,
              0.03801535815000534
            ],
            "deterministicId": <pointFourDeterministicId>,
            "snapPointType": <pointFourSnapPointType>,
            "type": "Onshape::Reference::Point",
            "uniqueId": <pointFourUniqueId>,
            "viewId": <pointFourViewId>
          }
        },
        "sectionLabelEndPosition": {
          "coordinate": [
            6.596052610858151,
            3.969982347423711,
            0.25000000000000006
          ],
          "type": "Onshape::Reference::Point"
        },
        "sectionLabelStartPosition": {
          "coordinate": [
            3.9715823474237117,
            6.594452610858151,
            0.25000000000000006
          ],
          "type": "Onshape::Reference::Point"
        },
        "showOffsetCutlines": false,
        "viewDirection": "Reverse", // Forward to flip direction of line and view
        "viewType": "Section"
    }]
  }]
}

Notes

  • To edit a section view, provide the section view’s logicalId. See Export the Drawing to JSON.
  • Required parameters:
    • attachmentPoints:
    • parentViewId:
    • position: Coordinate location to place the section view.
    • viewType: Must be Section for both create and edit messages.
    • sectionType:
      • Must be one of: Vertical | Horizontal | Angular
      • Cannot be edited once created.
  • Optional parameters can be specified during creation or edit:
    • isCutAngleEnabled: true to specify cutAngle.
    • cutAngle:
      • Available for Angular section types when isCutAngleEnabled is true
      • Positive values are clockwise. Negative values are counter-clockwise.
    • cutFromSection: true to indicate a section view is created from a section view.
    • showCutGeometry:
      • Only one of showCutGeometry or sectionDepth can be set.
      • true to display cut geometry.
    • sectionDepth:
      • Only one of showCutGeometry or sectionDepth can be set.
      • endType must be one of: UptoEntity | Blind.
      • offset is optional for UptoEntity.
      • For Blind, use:
        {
  "sectionDepth": {
    "depth": 0.0762,
    "endType": "Blind"
  }
}
    • labelDefinition:
      • Provide a label for the section.
      • Recommended but not required. Label will read as SECTION - if not provided.
    • sectionLabelStartPosition: Coordinates and type for the start of the label.
    • sectionLabelEndPosition: Coordinates and type for the end of the label.
    • joggedSectionLinePoints: Display section line points.
    • showOffsetCutlines: true to display the offset cutlines.
    • viewDirection: Reverse by default; set to Forward to flip the direction of the jogged section line and view.

Edit a view

You can edit a view by specifying the view’s logical ID or view ID in the request. Logical IDs are given higher priority.

This code edits the four views added in the previous example. Export a Drawing to JSON to obtain the logicalIds of the views to edit.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "description": "string",
  "jsonRequests": [ 
    {
      "messageName": "onshapeEditViews",
      "formatVersion": "2021-01-01",
      "views": [
        {
            "logicalId": "{view1LogicalId}",
            "renderMode": "quality",
            "showHiddenLines": true
        },
        {
            "logicalId": "{view2LogicalId}",
            "suppressAlignmentWithParent": true,
            "rotation": "45 * Math.PI/180",
        },
        {
            "viewId": "{view3ViewId}",
            "showShadedView": false,
            "showCentermarks": true,
            "showViewLabel": true,
            "showScaleLabel": true,
            "label": "Top View"
        },
        {
            "logicalId": "{view4ViewId}",
            "scale": {"scaleSource": "Parent"},
            "showHiddenLines": false,
            "sheet": {"index": 2}
        }]
    }]
}

Add and edit an auxiliary view

The code snippets below add auxiliary views from an existing edge in a drawing. Export a Drawing to JSON to obtain the reference edge’s IDs.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body - ISO

{
  "description": "string",
  "jsonRequests": [ 
    {
    "messageName": "onshapeCreateViews",
    "formatVersion": "2021-01-01",
    "description": "string",
    "views": [
      {
       "parentViewId": <viewId>,
       "position": {
        "x": 5.393,
        "y": 5.175
       },
       "viewType": "Auxiliary",
       "auxiliaryType": "Normal",
       "flipDirection": true,
       "referenceEntity": {
         "deterministicId": <deterministicId>,
         "type": "Onshape::Reference::Edge",
         "uniqueId": <uniqueId>,
         "viewId": <viewId>
       },
       "showViewReferenceIndicator": true,
       "viewIndicatorLabelPosition": {
         "coordinate": [
           -67.79156464044897,
           514.3687497136461,
           0
         ],
         "type": "Onshape::Reference::Point"
       },
       "viewingLinePosition": {
         "coordinate": [
           -54.40619175788366,
           531.1458708643852,
           0
         ],
         "type": "Onshape::Reference::Point"
       }
      }
     ]
    }
  ]
}

Request Body - ANSI


{
    "description": "string",
  "jsonRequests": [ 
    {
    "messageName": "onshapeCreateViews",
    "formatVersion": "2021-01-01",
    "description": "string",
    "views": [
      {
        "parentViewId": <viewId>,
        "position": {
          "x": 5.393,
          "y": 5.175
        },
        "viewType": "Auxiliary",
        "auxiliaryType": "InLine",
        "flipDirection": true,
        "referenceEntity": {
          "deterministicId": <deterministicId>,
          "type": "Onshape::Reference::Edge",
          "uniqueId": <uniqueId>,
          "viewId": <viewId>
        },
        "showViewReferenceIndicator": true,
        "viewingLineLabelEndPosition": {
          "coordinate": [
            7.763034116971886,
            3.7043508078693876,
            0
          ],
          "type": "Onshape::Reference::Point"
        },
        "viewingLineLabelStartPosition": {
          "coordinate": [
            6.966944610546761,
            3.2260119742374416,
            0
          ],
          "type": "Onshape::Reference::Point"
        },
        "viewingLineLength": 0.9287446053682189,
        "viewingLinePosition": {
          "coordinate": [
            7.1486733722971,
            3.8251916573483014,
            0
          ],
          "type": "Onshape::Reference::Point"
        }
      }
    ]
  }]
}

Notes

  • messageName : (Required) onshapeCreateViews | onshapeEditViews
  • viewType: (Required) Must be Auxiliary for both creating and editing.
  • auxiliaryType : (Required) Normal | InLine | Axis.
  • referenceEntity : (Required) Export a Drawing to JSON to obtain the entity’s IDs.
  • parentViewId: (Required) Export a Drawing to JSON to obtain the view ID of the parent view. Cannot be edited after creation.
  • position: (Required) Position to locate the view.
  • ISO templates take a label and line position. ANSI templates take starting and ending label positions, line position, and line length. See the examples above.
  • Additional properties that can be edited include:
    • auxiliaryType
    • referenceEntity
    • flipDirection
    • showViewReferenceIndicator
    • viewingLinePosition (ISO and ANSI)
    • viewIndicatorLabelPosition (ISO only)
    • viewingLineLabelStartPosition (ANSI only)
    • viewingLineLabelEndPosition (ANSI only)
    • viewingLineLength (ANSI only)

Examples - Dimensions

Add a dimension to a drawing

  1. Open an Onshape drawing. This example uses the drawing created in the Create a drawing from a part tutorial.
  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.com/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.com/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": "string",
        "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. Poll the modification status and wait for the modification to finish.
  6. Open your drawing and confirm that you see the new dimension.

Add a chamfer dimension to a drawing

  1. Open an Onshape drawing. This example uses the drawing created in the Create a drawing from a part tutorial.
  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.com/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::Chamfer to the drawing. We must specify the messageName and formatVersion for the modification, and then provide the information 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.com/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": "string",
        "jsonRequests": [ {
          "messageName": "onshapeCreateAnnotations",
          "formatVersion": "2021-01-01",
          "annotations": [
            {
              "chamferDimension": {
                "displayedValue": ".250 X 45.0°", // Display value
                "edge1End": {  
                    "coordinate": [
                        0.0,
                        -0.0063499999999999945,
                        0.012700000000000003
                    ],
                    "snapPointType": "ModeEnd",
                    "type": "Onshape::Reference::Point",
                    "uniqueId": "{edge1Id}", // Unique ID of the edge
                    "viewId": "{viewId}" // View ID of the drawing
                },
                "edge1Start": {
                    "coordinate": [
                        0.0063500000000000015,
                        0.0,
                        0.012700000000000003
                    ],
                    "snapPointType": "ModeStart",
                    "type": "Onshape::Reference::Point",
                    "uniqueId": "{edge1Id}", // Unique ID of the edge
                    "viewId": "{viewId}" // View ID of the drawing
                },
                "edge2End": {
                    "coordinate": [
                        0.07619999999999998,
                        0.0,
                        0.012700000000000003
                    ],
                    "snapPointType": "ModeEnd",
                    "type": "Onshape::Reference::Point",
                    "uniqueId": "{edge2Id}", // Unique ID of the edge
                    "viewId": "{viewId}" // View ID of the drawing
                },
                "edge2Start": {
                    "coordinate": [
                        0.0063500000000000015,
                        0.0,
                        0.012700000000000003
                    ],
                    "snapPointType": "ModeStart",
                    "type": "Onshape::Reference::Point",
                    "uniqueId": "{edge2Id}", // Unique ID of the edge
                    "viewId": "{viewId}" // View ID of the drawing
                },
                "firstChamferOverride": "", // Override the first value in the displayedValue field
                "formatting": {
                    "dimdec": 3.0,
                    "dimlim": false,
                    "dimpost": " POST",
                    "dimtm": 0.0,
                    "dimtol": false,
                    "dimtp": 0.0,
                    "type": "Onshape::Formatting::Dimension"
                },
                "logicalId": "h:10000124",
                "measurementAngle": 0.7853981633974478, // Angle of the chamfer
                "measurementLength": 0.2500000000000002, // Length of the chamfer
                "prefix": "PRE ", // Text to appear before the display value
                "secondChamferOverride": "", // Override the second value in the displayedValue field
                "suffix": " POST", // Text to appear after the display value
                "textAbove": "ABOVE", // Text to appear above the display value
                "textBelow": "BELOW", // Text to appear below the display value
                "textPosition": { // Location of display value
                    "coordinate": [
                        1.114880743466248,
                        6.783806096154582,
                        0.0
                    ],
                    "type": "Onshape::Reference::Point"
                }
            },
            "type": "Onshape::Dimension::Chamfer"
            }
          ]  
        }]
      }'
  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. Poll the modification status and wait for the modification to finish.
  6. Open your drawing and confirm that you see the new chamfer dimension.

Create ordinate dimensions

Create ordinate dimensions (also known as (X, Y) pairs) for a feature measured from a datum. Ordinate dimensions created as a group move together when one is moved.

  • Export the Drawing to JSON to obtain the point coordinates and the deterministic and view IDs to specify.
  • To edit an ordinate dimension, use messageName = onshapeEditAnnotations and provide the dimension’s logicalId
  • Stack the dimension group horizontally or vertically with dimensionGroup.type = horizontal | vertical


ordinate dimension examples

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "description": "string",
  "jsonRequests": [ {  
    "messageName": "onshapeCreateAnnotations",  
    "formatVersion": "2021-01-01",  
    "annotations": [  
      {  
        "ordinateDimension": {
          "dimensionGroup": [
            {
              "attachmentPoint": {
                "coordinate": [<xOne>, <yOne>, <zOne>],
                "deterministicId": <deterministicIdPointOne>,
                "snapPointType": "ModeStart",
                "type": "Onshape::Reference::Point",
                "viewId": <viewIdDrawing>
              },
              "isOrigin": true,
              "textPosition": {
                "coordinate": [<xTwo>, <yTwo>, <zTwo>],
                "type": "Onshape::Reference::Point"
              }
            },
            {
              "attachmentPoint": {
                "coordinate": [<xThree>, <yThree>, <zThree>],
                "deterministicId": <deterministicIdPointTwo>,
                "snapPointType": "ModeStart",
                "type": "Onshape::Reference::Point",
                "viewId": <viewIdDrawing>
              },
              "isOrigin": false,
              "textPosition": {
                "coordinate": [<xFour>, <yFour>, <zFour>],
                "type": "Onshape::Reference::Point"
              }
            }
          ],
          "type": "vertical"
        },
        "type": "Onshape::Dimension::Ordinate"
      }]
  }]
}

Add an arc length dimension

An arc length dimension measures the length along a curved edge. Specify the arc and a text position; the center and end points are taken from the arc.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Properties

  • edge - Required to create. The arc edge to dimension. On edit, the dimension can be re-attached to a different arc.
  • textPosition - Required to create. Coordinates for the text and dimension arc.
  • conjugateArc - Optional.
    • Set to true to measure the conjugate arc (the part of the edge’s circle that the edge does not cover).
    • With conjugateArc: true, place textPosition on the conjugate side. A text position on the edge’s side is accepted, but the next view update measures the edge again.
    • If omitted on create, the dimension measures the edge itself.
    • If omitted on edit, the dimension is unchanged.
    • Always returned in export.
  • unit - Required to create.
  • logicalId – Required to edit. The ID of the dimension to edit.
  • measurement, displayedValue – Supported in export only.

Notes

  • Export the Drawing to JSON to obtain the required IDs and coordinates.
  • Supported for an arc or an arc segment of a polyline.
    • Full circles and straight lines are rejected.
  • Partial arcs, leaders, and the position of the arc symbol are not supported; the symbol follows the drawing standard.
  • An edit cannot move the dimension to another sheet.

Request Body - Create

{
  "description": "string",
  "jsonRequests": [
    {
      "messageName": "onshapeCreateAnnotations",
      "formatVersion": "2021-01-01",
      "annotations": [
        {
          "type": "Onshape::Dimension::ArcLength",
          "arcLengthDimension": {
            "edge": {
              "type": "Onshape::Reference::Edge",
              "viewId": <viewIdOne>,
              "uniqueId": <uniqueIdEdgeOne>
            },
            "textPosition": {
              "type": "Onshape::Reference::Point",
              "coordinate": [
                4.7163,
                3.2208,
                0
              ]
            },
            "unit": {
              "unit": "Inches"
            },
            "isPrecisionOverridden": true,
            "precision": 3
          }
        }
      ]
    }
  ]
}

Request Body - Edit

{
  "description": "string",
  "jsonRequests": [
    {
      "messageName": "onshapeEditAnnotations",
      "formatVersion": "2021-01-01",
      "annotations": [
        {
          "type": "Onshape::Dimension::ArcLength",
          "arcLengthDimension": {
            "logicalId": <logicalIdArcLengthDimOne>,
            "textAbove": "ABOVE",
            "prefix": "P-",
            "isPrecisionOverridden": true,
            "precision": 4,
            "displayParentheses": true,
            "inspection": true
          }
        }
      ]
    }
  ]
}

Add a threaded dimension

There is no specific threaded dimension type. A point-to-point, point-to-line, or line-to-line dimension placed on the thread edges of a hole or thread, and sent with isThreadedDimension: true, becomes a threaded dimension. The text shows the thread callout (for example M5x.80) or the thread depth, and the export marks it with isThreadedDimension: true.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Notes

  • Export the Drawing to JSON to obtain the IDs and coordinates needed.
  • isThreadedDimension - Required (true) to create a threaded dimension. Without it, or with false, a plain dimension is created, even on thread edges.
    • On edges that are not thread edges, a plain dimension is created, with no error.
    • Ignored on edit: a dimension cannot be changed between threaded and plain.
    • Returned in export only on a threaded dimension, so an exported dimension can be sent back to create as it is.
  • textOverride is exported only on a threaded dimension to hold the thread callout or depth. A value sent on create or edit is ignored, with no error. prefix, suffix, textAbove, and textBelow still apply.
  • The exported coordinates can differ from the ones sent; the dimension snaps to the thread geometry, as in the Onshape UI.

Request Body - Create

Creates a dimension between two edges of the same thread.

{
  "description": "string",
  "jsonRequests": [
    {
      "messageName": "onshapeCreateAnnotations",
      "formatVersion": "2021-01-01",
      "annotations": [
        {
          "type": "Onshape::Dimension::LineToLine",
          "lineToLineDimension": {
            "edge1": {
              "type": "Onshape::Reference::Edge",
              "viewId": <viewIdOne>,
              "uniqueId": <uniqueIdEdgeOne>
            },
            "edge2": {
              "type": "Onshape::Reference::Edge",
              "viewId": <viewIdOne>,
              "uniqueId": <uniqueIdEdgeTwo>
            },
            "textPosition": {
              "type": "Onshape::Reference::Point",
              "coordinate": [
                3.5727,
                4.0895,
                0
              ]
            },
            "unit": {
              "unit": "Inches"
            },
            "isThreadedDimension": true
          }
        }
      ]
    }
  ]
}

Exported JSON (trimmed)

{
  "type": "Onshape::Dimension::LineToLine",
  "lineToLineDimension": {
    "logicalId": "h:100008C2",
    "textOverride": "M5x.80",
    "displayedValue": "M5x.80",
    "isThreadedDimension": true
  }
}

Add a minimum or maximum dimension

A min/max dimension measures the smallest or largest distance between two circles or arcs, such as two holes. It is a point-to-point or point-to-line dimension whose circle points carry anchorType: min for the nearest point of the circle, and anchorType: max for the farthest.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Properties

  • coordinate - Required on create. The coordinate sent is only a hint; the exact point is computed.
  • anchorType - Optional, on each point object (point1 and point2 for point-to-point, point for point-to-line). min uses the nearest point of the circle, max the farthest.
  • measurement – Export only; the computed min/max distance.

Notes

  • Export the Drawing to JSON to obtain the IDs and coordinates needed.
  • Only point-to-point and point-to-line dimensions are supported for circles or arcs.
  • A min/max dimension cannot be turned back into a normal one.
  • For concentric circles or arcs, no single nearest or farthest point exists, so the coordinates give the direction:
    • Both ends go on the ray from the center through point2 (or point1), then textPosition, if it is at the center.
    • With max, the ends are on opposite sides of the center.
  • Between concentric circles, min and max cannot be mixed.
    • At least one of point1, point2, and textPosition must be off the center, and that direction must cross both circles.
    • rotation is not accepted.
  • On edit, include anchorType on every point you send; a point you leave out keeps its anchor.

Request Body - Create

Creates one dimension from the nearest point of one hole to the farthest point of the other.

{
  "description": "string",
  "jsonRequests": [
    {
      "messageName": "onshapeCreateAnnotations",
      "formatVersion": "2021-01-01",
      "annotations": [
        {
          "type": "Onshape::Dimension::PointToPoint",
          "pointToPointDimension": {
            "point1": {
              "type": "Onshape::Reference::Point",
              "viewId": <viewId>,
              "deterministicId": <deterministicIdPointOne>,
              "coordinate": [
                -0.0134,
                -0.0066,
                0.0254
              ],
              "anchorType": "min"
            },
            "point2": {
              "type": "Onshape::Reference::Point",
              "viewId": <viewId>,
              "deterministicId": <deterministicIdPointTwo>,
              "coordinate": [
                0.0003,
                -0.0151,
                0.0254
              ],
              "anchorType": "max"
            },
            "textPosition": {
              "type": "Onshape::Reference::Point",
              "coordinate": [
                3.3158,
                6.7971,
                0
              ]
            },
            "unit": {
              "unit": "Inches"
            }
          }
        }
      ]
    }
  ]
}

Add a wall thickness dimension

A wall thickness dimension measures the wall between two concentric circular edges, such as a tube or a bore. It is a point-to-point dimension with one point on each concentric edge; the export marks it with isWallThicknessDimension: true.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Notes

  • Export the Drawing to JSON to obtain the IDs and coordinates needed.
  • isWallThicknessDimension is export only. It is ignored on create, and an edit that changes it is refused.
  • The dimension is recognized only when both points lie on concentric circles, arcs, or centermarks, and neither point has an anchorType; otherwise a normal dimension (or a min/max dimension) is created, with no error.
  • Moving the points on edit does not re-check whether it is still a wall thickness dimension.

Request Body - Create

{
  "description": "string",
  "jsonRequests": [
    {
      "messageName": "onshapeCreateAnnotations",
      "formatVersion": "2021-01-01",
      "annotations": [
        {
          "type": "Onshape::Dimension::PointToPoint",
          "pointToPointDimension": {
            "point1": {
              "type": "Onshape::Reference::Point",
              "viewId": <viewId>,
              "deterministicId": <deterministicIdPointOne>,
              "snapPointType": "ModeNear",
              "coordinate": [
                0.0205,
                0.015,
                0.0254
              ]
            },
            "point2": {
              "type": "Onshape::Reference::Point",
              "viewId": <viewId>,
              "deterministicId": <deterministicIdPointTwo>,
              "snapPointType": "ModeNear",
              "coordinate": [
                0.041,
                0.03,
                0.0254
              ]
            },
            "textPosition": {
              "type": "Onshape::Reference::Point",
              "coordinate": [
                10.15,
                8.792,
                0
              ]
            },
            "unit": {
              "unit": "Inches"
            }
          }
        }
      ]
    }
  ]
}

Add text or symbols to a dimension

You can add text or symbols to display with any dimension:


annotation with text above, below, before, and after the dimension

Add the following fields to any dimension definition.

{
  "prefix": "%%c",  
  "suffix": " (x20)",  
  "textAbove": "FLAT WASHER",  
  "textBelow": "STEEL"
}

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "description": "string",
  "jsonRequests": [ {  
    "messageName": "onshapeCreateAnnotations",  
    "formatVersion": "2021-01-01",  
    "annotations": [  
      {  
        "lineToLineDimension": {
          // ...  
          "prefix": "%%c",  
          "suffix": " (x20)",  
          "textAbove": "FLAT WASHER",  
          "textBelow": "STEEL"
          // ...
        },
        "type": "Onshape::Dimension::LineToLine"  
      }]  
  }]
}

If editing an existing dimension, export the Drawing to JSON to obtain the dimension’s logical ID.

{
  "description": "string",
  "jsonRequests": [ {  
    "messageName": "onshapeEditAnnotations",  
    "formatVersion": "2021-01-01",  
    "annotations": [  
      {  
        "pointToPointDimension": {  
          "logicalId": "h:10000675",  
          "prefix": "Prefix",  
          "suffix": "Suffix",  
          "textAbove": "Above",  
          "textBelow": "Below"
        },  
        "type": "Onshape::Dimension::PointToPoint"  
      }]  
  }]
}

Set dimension precision

By default, precision is set in the Onshape Drawings Properties panel, and the isPrecisionOverridden field in API is set to false.

To manually set the precision value when creating or editing a dimension via the API, set isPrecisionOverridden to true to override the value in the Onshape Drawings Properties panel.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Bodies

To set precision, set isPrecisionOverridden to true and supply the precision field:

{
  "description": "string",
  "jsonRequests": [ {  
    "messageName": "onshapeEditAnnotations",  
    "formatVersion": "2021-01-01",  
    "annotations": [  
      {  
        "lineToLineDimension": {  
          "logicalId": "h:100001DD",
          "isPrecisionOverridden": true,
          "precision": 3
        },  
        "type": "Onshape::Dimension::LineToLine"  
      }]  
  }]
}

Break or unbreak a dimension

breakDimensionLine sets whether a dimension’s lines are broken where other dimensions or view geometry cross them, the same as the Break dimension and Unbreak dimension commands in the Onshape UI. It applies to point-to-point, point-to-line, line-to-line, three-point angular, line-to-line angular, radial, diametric, arc length and ordinate dimensions.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Notes

  • Export the Drawing to JSON to obtain the logical IDs needed.
  • If omitted on create, the drawing’s Break dimension by default setting applies; if omitted on edit, the state is unchanged.
  • The API sets only on/off; the gap size and where gaps fall come from the dimension style and the crossing geometry.
  • Ordinate dimensions are broken one at a time; the property is on each item of dimensionGroup, not on the group.
  • Chamfer dimensions, hole callouts, and other annotation types are not supported.

Request Body - Edit

Unbreaks a radial dimension and breaks a diametric dimension.

{
  "description": "string",
  "jsonRequests": [
    {
      "messageName": "onshapeEditAnnotations",
      "formatVersion": "2021-01-01",
      "annotations": [
        {
          "type": "Onshape::Dimension::Radial",
          "radialDimension": {
            "logicalId": <logicalIdDimensionOne>,
            "breakDimensionLine": false
          }
        },
        {
          "type": "Onshape::Dimension::Diametric",
          "diametricDimension": {
            "logicalId": <logicalIdDimensionTwo>,
            "breakDimensionLine": true
          }
        }
      ]
    }
  ]
}

Add jogs to dimension extension lines

A jog makes an extension line step sideways along a short slanted segment before it reaches the dimension line, the same as the Add jog command. Point-to-point, point-to-line and line-to-line dimensions take an extensionLineJogs array with at most one jog per extension line. A jog that gives only extensionLineIndex gets the same measurements as the Add jog command.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Properties

  • extensionLineJogs - Optional. At most 2 items.
    • If omitted on edit, the jogs are unchanged.
    • If an empty array is sent on edit ([]), all jogs removed.
  • extensionLineIndex - Required. 0 for the first extension line; 1 for the second.
  • startDistance - Optional. Drawing units from the dimensioned point along the extension line.
  • jogLength - Optional. Length of the slanted segment in the drawing’s units.
  • jogAngle - Optional. Degrees of the jog; negative steps toward the inside of the dimension line.

Notes

  • Export the Drawing to JSON to obtain the logical IDs needed.
  • On edit, the array is the full list: a jogged extension line missing from the array loses its jog.
  • If the drawing locks jogged dimensions to 45 degrees, jogAngle comes back as 45 or -45, keeping only its sign.
  • A jog on an extension line too short to hold it moves the dimension line and text; textPosition changes.
  • Angular, radial, and other dimensions do not take jogs; a wall thickness dimension with jogs is rejected.

Request Body - Create

Creates a jogged extension line.

{
  "description": "string",
  "jsonRequests": [
    {
      "messageName": "onshapeCreateAnnotations",
      "formatVersion": "2021-01-01",
      "annotations": [
        {
          "type": "Onshape::Dimension::PointToPoint",
          "pointToPointDimension": {
            "point1": {
              "type": "Onshape::Reference::Point",
              "viewId": <viewId>,
              "deterministicId": <deterministicIdPointOne>,
              "uniqueId": <uniqueIdPointOne>,
              "snapPointType": "ModeEnd",
              "coordinate": [
                -0.067,
                -0.0684,
                0.0254
              ]
            },
            "point2": {
              "type": "Onshape::Reference::Point",
              "viewId": <viewId>,
              "deterministicId": <deterministicIdPointTwo>,
              "uniqueId": <uniqueIdPointTwo>,
              "snapPointType": "ModeEnd",
              "coordinate": [
                0.067,
                -0.0684,
                0.0254
              ]
            },
            "textPosition": {
              "type": "Onshape::Reference::Point",
              "coordinate": [
                6.4841,
                3.1317,
                0
              ]
            },
            "unit": {
              "unit": "Inches"
            },
            "extensionLineJogs": [
              {
                "extensionLineIndex": 0
              }
            ]
          }
        }
      ]
    }
  ]
}

Request Body - Edit

Reshapes the jog on the first dimension and removes all jogs from another dimension.

{
  "description": "string",
  "jsonRequests": [
    {
      "messageName": "onshapeEditAnnotations",
      "formatVersion": "2021-01-01",
      "annotations": [
        {
          "type": "Onshape::Dimension::PointToPoint",
          "pointToPointDimension": {
            "logicalId": <logicalIdDimensionOne>,
            "extensionLineJogs": [
              {
                "extensionLineIndex": 0,
                "startDistance": 0.625,
                "jogLength": 0.9,
                "jogAngle": -30
              },
              {
                "extensionLineIndex": 1
              }
            ]
          }
        },
        {
          "type": "Onshape::Dimension::PointToPoint",
          "pointToPointDimension": {
            "logicalId": <logicalIdDimensionTwo>,
            "extensionLineJogs": []
          }
        }
      ]
    }
  ]
}

Show and hide dimension and extension lines

Three boolean properties match the Style panel checkboxes:

  • showFirstExtensionLine - Supported for linear, angular, and arc length dimensions. On radial/diametric dimensions, this is the extension arc.
  • showSecondExtensionLine - Supported for linear, angular, and arc length dimensions only.
  • showDimensionLine - Supported for radial and diametric dimensions only.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Notes

  • Export the Drawing to JSON to obtain the logical IDs of the dimension.
  • If omitted on create, the drawing default applies. If omitted on edit, the current value is kept.
  • Lines that a dimension never draws (for example both extension lines of a wall thickness dimension) are ignored and export as false.
  • showDimensionLine is rejected on a radial or diametric dimension attached to a silhouette edge and on a foreshortened radial.

Request Body - Edit

Hides the two extension lines of a point-to-point dimension. Hides the dimension line of a radial dimension.

{
  "description": "string",
  "jsonRequests": [
    {
      "messageName": "onshapeEditAnnotations",
      "formatVersion": "2021-01-01",
      "annotations": [
        {
          "type": "Onshape::Dimension::PointToPoint",
          "pointToPointDimension": {
            "logicalId": <logicalIdDimensionOne>,
            "showFirstExtensionLine": false,
            "showSecondExtensionLine": false
          }
        },
        {
          "type": "Onshape::Dimension::Radial",
          "radialDimension": {
            "logicalId": <logicalIdDimensionTwo>,
            "showDimensionLine": false
          }
        }
      ]
    }
  ]
}

Examples - Tolerances

Add a dimension with a symmetrical tolerance

Export a Drawing to JSON to obtain the deterministic, unique, and view IDs to specify.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "description": "string",
  "jsonRequests": [ {  
    "messageName": "onshapeCreateAnnotations",  
    "formatVersion": "2021-01-01",  
    "annotations": [  
      {  
        "pointToPointDimension": {  
          "point1": {  
            "coordinate": [  
              -0.022788484925716336,  
              0.06710318401608831,  
              0.004825999999999999  
            ],  
            "deterministicId": "JIV",  
            "snapPointType": "ModeEnd",  
            "type": "Onshape::Reference::Point",  
            "uniqueId": "F4245",  
            "viewId": "2b2608befce5281dc1f651e9"  
          },  
          "point2": {  
            "coordinate": [  
              0.06483851512571645,  
              0.06710318401608831,  
              0.004825999999999999  
            ],  
            "deterministicId": "JIV",  
            "snapPointType": "ModeStart",  
            "type": "Onshape::Reference::Point",  
            "uniqueId": "F4245",  
            "viewId": "2b2608befce5281dc1f651e9"  
          },
          "textPosition": {  
            "coordinate": [  
              4.8346992569387219,  
              5.660045658601707,  
              0  
            ],  
            "type": "Onshape::Reference::Point"  
          },  
          "tolerance": {  
            "type": "Symmetrical",  
            "upperValue": 2.14  
          }
        },  
        "type": "Onshape::Dimension::PointToPoint"  
      }]
  }]
}

Add a dimension with a basic tolerance

Export a Drawing to JSON to obtain the IDs of the edges and views.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "description": "string",
  "jsonRequests": [ {  
    "messageName": "onshapeCreateAnnotations",  
    "formatVersion": "2021-01-01",  
    "annotations": [  
      {  
        "lineToLineDimension": {  
          "edge1": {  
            "deterministicId": "JIV",  
            "type": "Onshape::Reference::Edge",  
            "uniqueId": "F4245",  
            "viewId": "2b2608befce5281dc1f651e9"  
          },  
          "edge2": {  
            "deterministicId": "JJV",  
            "type": "Onshape::Reference::Edge",  
            "uniqueId": "F4243",  
            "viewId": "2b2608befce5281dc1f651e9"  
          },  
          "rotation": 0,  
          "textOverride": "",  
          "textPosition": {  
            "coordinate": [  
              4.731016024253847,  
              3.189199999999999,  
              0  
            ],  
            "type": "Onshape::Reference::Point"
          },  
          "tolerance": {  
            "type": "Basic"  
          }  
        },  
        "type": "Onshape::Dimension::LineToLine"  
      }]  
  }]
}

Add a dimension with a deviation tolerance

Export a Drawing to JSON to obtain the IDs to specify.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "description": "string",
  "jsonRequests": [ {  
    "messageName": "onshapeCreateAnnotations",  
    "formatVersion": "2021-01-01",  
    "annotations": [  
      {  
        "pointToPointDimension": {  
          "point1": {  
            "coordinate": [  
              -0.022788484925716308,  
              0.06710318401608836,  
              0.004825999999999999  
            ],  
            "deterministicId": "JIV",  
            "snapPointType": "ModeEnd",  
            "type": "Onshape::Reference::Point",  
            "uniqueId": "F4245",  
            "viewId": "2b2608befce5281dc1f651e9"  
          },  
          "point2": {  
            "coordinate": [  
              0.0648385151257165,  
              0.06710318401608836,  
              0.004825999999999999  
            ],  
            "deterministicId": "JIV",  
            "snapPointType": "ModeStart",  
            "type": "Onshape::Reference::Point",  
            "uniqueId": "F4245",  
            "viewId": "2b2608befce5281dc1f651e9"
          },  
          "rotation": 0,  
          "textPosition": {  
            "coordinate": [  
              6.379999999999999,  
              9.903619353521464,  
              0  
            ],  
            "type": "Onshape::Reference::Point"  
          },  
          "tolerance": {  
            "lowerValue": 1.52,  
            "type": "Deviation",  
            "upperValue": 4.25  
          } 
        },  
        "type": "Onshape::Dimension::PointToPoint"  
      }]  
  }]
}

Add a dimension with a limit tolerance

Export a Drawing to JSON to obtain the IDs to specify.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "description": "string",
  "jsonRequests": [ {  
    "messageName": "onshapeCreateAnnotations",  
    "formatVersion": "2021-01-01",  
    "annotations": [  
      {  
        "pointToPointDimension": {  
          "point1": {  
            "coordinate": [  
              -0.022788484925716308,
              0.06710318401608836,  
              0.004825999999999999  
            ],  
            "deterministicId": "JIV",  
            "snapPointType": "ModeEnd",  
            "type": "Onshape::Reference::Point",  
            "uniqueId": "F4245",  
            "viewId": "2b2608befce5281dc1f651e9"  
          },  
          "point2": {  
            "coordinate": [  
              0.0648385151257165,  
              0.06710318401608836,  
              0.004825999999999999  
            ],  
            "deterministicId": "JIV",  
            "snapPointType": "ModeStart",  
            "type": "Onshape::Reference::Point",  
            "uniqueId": "F4245",  
            "viewId": "2b2608befce5281dc1f651e9"  
          },  
          "rotation": 0,  
          "textPosition": {  
            "coordinate": [  
              6.379999999999999,  
              9.492751572521588,  
              0  
            ],  
            "type": "Onshape::Reference::Point"  
          },  
          "tolerance": {  
            "lowerValue": 2.5,  
            "type": "Limit",  
            "upperValue": 4.5  
          } 
        },  
        "type": "Onshape::Dimension::PointToPoint"  
      }]  
  }]
}

Add a dimension with a minimum tolerance

Export a Drawing to JSON to obtain the IDs to specify.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "description": "string",
  "jsonRequests": [ {  
    "messageName": "onshapeCreateAnnotations",  
    "formatVersion": "2021-01-01",  
    "annotations": [  
      {  
        "pointToPointDimension": {  
          "point1": {  
            "coordinate": [  
              -0.022788484925716308,  
              0.06710318401608836,  
              0.004825999999999999  
            ],  
            "deterministicId": "JIV",  
            "snapPointType": "ModeEnd",  
            "type": "Onshape::Reference::Point",  
            "uniqueId": "F4245",  
            "viewId": "2b2608befce5281dc1f651e9"  
          },  
          "point2": {  
            "coordinate": [  
              0.0648385151257165,  
              0.06710318401608836,  
              0.004825999999999999  
            ],  
            "deterministicId": "JIV",  
            "snapPointType": "ModeStart",  
            "type": "Onshape::Reference::Point",  
            "uniqueId": "F4245",  
            "viewId": "2b2608befce5281dc1f651e9"
          },  
          "textPosition": {  
            "coordinate": [  
              6.379999999999999,  
              9.61398841181059,  
              0  
            ],  
            "type": "Onshape::Reference::Point"  
          },  
          "tolerance": {  
            "type": "MIN"  
          } 
        },  
        "type": "Onshape::Dimension::PointToPoint"  
      }]  
  }]
}

Add a dimension with a maximum tolerance

Export a Drawing to JSON to obtain the IDs to specify.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "description": "string",
  "jsonRequests": [ {  
    "messageName": "onshapeCreateAnnotations",  
    "formatVersion": "2021-01-01",  
    "annotations": [  
      {  
        "pointToPointDimension": {  
          "point1": {  
          "coordinate": [  
              -0.022788484925716308,  
              0.06710318401608836,  
              0.004825999999999999  
            ],
            "deterministicId": "JIV",  
            "snapPointType": "ModeEnd",  
            "type": "Onshape::Reference::Point",  
            "uniqueId": "F4245",  
            "viewId": "2b2608befce5281dc1f651e9"  
          },  
          "point2": {  
            "coordinate": [  
              0.0648385151257165,  
              0.06710318401608836,  
              0.004825999999999999  
            ],  
            "deterministicId": "JIV",  
            "snapPointType": "ModeStart",  
            "type": "Onshape::Reference::Point",  
            "uniqueId": "F4245",  
            "viewId": "2b2608befce5281dc1f651e9"  
          },  
          "textPosition": {  
            "coordinate": [  
              2.6531471291300536,  
              6.378399999999999,  
              0  
            ],  
            "type": "Onshape::Reference::Point"  
          },  
          "tolerance": {  
            "type": "MAX"  
          } 
        },  
        "type": "Onshape::Dimension::PointToPoint"  
      }]
  }]
}

Add a dimension with a fit class tolerance

You can add three types of fit class tolerance to a dimension (Fit | FitWithTolerance | FitToleranceOnly):

{
  "tolerance": {  
    "fitType": "Clearance | Transition | Interference | Userdefined",  
    "holeClass": "H8", 
    "precision": 6, 
    "shaftClass": "e7",  
    "type": "Fit | FitWithTolerance | FitToleranceOnly" 
  }  
}

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "description": "string",
  "jsonRequests": [ {  
    "messageName": "onshapeCreateAnnotations",  
    "formatVersion": "2021-01-01",  
    "annotations": [  
      {  
        "lineToLineDimension": {  
          // ...
          "tolerance": {  
            "fitType": "Clearance",  
            "holeClass": "H8",  
            "precision": 6,
            "shaftClass": "e7",
            "type": "FitWithTolerance"  
          }  
        },  
        "type": "Onshape::Dimension::LineToLine"  
      }]  
  }]
}

If editing an existing dimension, export the Drawing to JSON to obtain the dimension’s logical ID.

{
  "description": "string",
  "jsonRequests": [ {  
    "messageName": "onshapeEditAnnotations",  
    "formatVersion": "2021-01-01",  
    "annotations": [  
      {  
        "pointToPointDimension": {  
          "logicalId": "h:10000675",  
          "tolerance": {  
            "fitType": "Interference",  
            "holeClass": "H7",  
            "precision": 6,
            "shaftClass": "f6",  
            "type": "FitToleranceOnly"  
          }
        },  
        "type": "Onshape::Dimension::PointToPoint"  
      }]  
  }]
}

Add a tolerance to an existing dimension

Export a Drawing to JSON to obtain the dimension’s logical ID.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "description": "string",
  "jsonRequests": [ {  
    "messageName": "onshapeEditAnnotations",  
    "formatVersion": "2021-01-01",  
    "annotations": [  
      {  
      "pointToPointDimension": {  
        "logicalId": "h:10000A0A",  
        "tolerance": {  
          "lowerValue": 2.14000001,  
          "type": "Deviation",  
          "upperValue": 2.140000001
        }  
      },  
      "type": "Onshape::Dimension::PointToPoint"  
      }  
    ]  
  }]
}

Edit a dimension tolerance type

Export a Drawing to JSON to obtain the dimension’s logical ID.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "description": "string",
  "jsonRequests": [ {  
    "messageName": "onshapeEditAnnotations",  
    "formatVersion": "2021-01-01",  
    "annotations": [  
      {  
      "lineToLineDimension": {  
        "logicalId": "h:10000A3D",  
        "tolerance": {  
          "type": "None"  
        } 
      },  
      "type": "Onshape::Dimension::LineToLine"  
      }]
  }]
}

Examples - Other

Delete drawing entities

Use the onshapeDeleteEntities message to delete annotations, dimensions, views, callouts, tables, and notes from a drawing. Bend notes cannot be deleted. Export the drawing to JSON to get the logicalId for each entity to delete.

Endpoint

POST /drawings/d/did/w/wid/e/eid/modify

Request Body

{
  "formatVersion": "2021-01-01",
  "messageName": "onshapeDeleteEntities",
  "description": "string",
  "entities": [
    "h:10000378",
    "h:1000037D",
    "h:10000383"
  ]
}

Find dangling entities

To identify 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.

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

ℹ️ NOTE

  • 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 response, 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.

Find bounding box details

  1. Export a drawing to JSON.
  2. For each bounding box in the drawing, the response includes a boundingBoxPoints field that specifies the box coordinates.

Additional Resources