create_sketch
Creates an Onshape sketch by defining geometry with coordinates or constraints, supporting lines, circles, arcs, and rectangles.
Instructions
Create ONE sketch feature atomically. Two surfaces in one tool:
Coordinate-first (legacy, for simple sketches): pass entity dicts without id and no constraints. The builder hand-computes positions from your coordinates. Fast for 1–3 primitives where you already know where everything goes.
Constraint-first (for drawing transcription): give each entity a user-level id, list real-world constraints between them, and let Onshape's solver resolve positions. This is how the UI works and how engineering drawings are specified.
Sketch location: pass either plane (Front/Top/Right) or faceId (from list_entities or the feature_id of a create_offset_plane). faceId wins when both are given.
Coordinate-first entity types
rectangle: {type, corner1:[x,y], corner2:[x,y], variableWidth?, variableHeight?} rounded_rectangle: {type, corner1:[x,y], corner2:[x,y], cornerRadius} circle: {type, center:[x,y], radius, variableRadius?, variableCenter?:[xv,yv]} line: {type, start:[x,y], end:[x,y]} arc: {type, center:[x,y], radius, startAngle?, endAngle?, variableRadius?, variableCenter?:[xv,yv]}
Constraint-first entity types (require id)
line: {type:'line', id, start:[x,y]?, end:[x,y]?, construction?}
circle: {type:'circle', id, center:[x,y], radius, construction?}
arc: {type:'arc', id, center:[x,y], radius, start_angle?, end_angle?, short_arc?, construction?}
— short_arc defaults true: if CCW sweep > 180° the builder silently swaps endpoints so the arc goes the short way (matches Onshape UI's three-point-arc default). Set false for the explicit long-way case.
point: {type:'point', id, at:[x,y]?, construction?}
Circle / arc SEEDS (center + radius) are required even when a DIAMETER or RADIUS constraint will drive the final value — Onshape's solver needs a starting guess. Line start/end are optional; seed to [0,0] when omitted and let COINCIDENT / TANGENT constraints pull endpoints into position.
Constraints (constraint-first surface only)
Each item: {type, entities?:[id,...] | entity?:id, value?, direction?}.
Entity refs are ids, optionally with a sub-point suffix:
line.start, line.end, circle.center, arc.center
Supported types:
Entity-ref only: HORIZONTAL, VERTICAL (LINES ONLY — not points), COINCIDENT, TANGENT, CONCENTRIC, PARALLEL, PERPENDICULAR, EQUAL, MIDPOINT
Dimensioned: DIAMETER, RADIUS, DISTANCE (add direction: HORIZONTAL|VERTICAL|MINIMUM), ANGLE (value in degrees by default — string "90 deg" / "1.57 rad" for explicit units)
Binary pair: OFFSET (offset entity + master — pair it with a DISTANCE constraint on the same two for the offset length)
Aliases: HORIZONTAL_DISTANCE → DISTANCE(direction=HORIZONTAL), VERTICAL_DISTANCE → DISTANCE(direction=VERTICAL), LENGTH → DISTANCE(direction=MINIMUM) (for line-length or slot end-to-end dimensions).
POINT_ON is NOT a separate type — use COINCIDENT with a point sub-ref.
Pinning to the sketch origin
There is no magic origin keyword. To anchor geometry to the sketch plane origin (prevents drift on parametric resize), add a point entity at [0,0] and COINCIDENT to it:
entities: [{id:'origin', type:'point', at:[0,0]}, ...]
constraints: [{type:'COINCIDENT', entities:['hub.center', 'origin']}, ...]
This gives you a sketch-local anchor the solver treats as fixed.
Bare numbers are mm; pass strings like "10 mm" / "0.5 in" for explicit units.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Sketch name | Sketch |
| plane | No | Standard datum plane. Defaults to Front if neither plane nor faceId is given. | |
| faceId | No | Deterministic ID of an existing face (from `list_entities`). Mutually exclusive with `plane`; wins if both given. | |
| entities | Yes | Mixed list of sketch primitives. Presence of `id` on an entity switches to the constraint-first surface (single-entity circles / arcs / lines + solver-driven positions). See tool description for per-type fields. | |
| elementId | Yes | Part Studio element ID | |
| documentId | Yes | Document ID | |
| constraints | No | Constraint-first sketch solver directives. Each item: {type, entities?:[id,...] | entity?:id, value?, direction?}. See tool description for supported types + entity-ref syntax. | |
| workspaceId | Yes | Workspace ID |