Forge Documentation

Python API Reference

ForgeCAD exposes a WebSocket JSON-RPC API. The Python package wraps this API — you can also call it directly from any language.

Authentication

All API connections require an API key. Set it as an environment variable or pass it in the connection URL:

# Environment variable (recommended)
export FORGE_API_KEY=fsk_live_xxxxxxxxxxxx

# Or in the Python client
import forgecad as fc
fc.connect(api_key="fsk_live_xxxxxxxxxxxx")

API keys are scoped to a workspace. Generate them in the customer portal under Settings → API Keys.

WebSocket protocol

The API uses JSON-RPC 2.0 over WebSocket on port 8765. Every request has the form:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "document.create",
  "params": { "title": "My Model" }
}

Responses:

// Success
{ "jsonrpc": "2.0", "id": 1, "result": { "id": "doc_abc123" } }

// Error
{ "jsonrpc": "2.0", "id": 1, "error": { "code": -32602, "message": "Invalid params" } }

Event notifications (from events.subscribe) are server-initiated messages with no id field:

{ "jsonrpc": "2.0", "method": "notify", "params": { "event": "document.modified", "id": "doc_abc123" } }

Python client quickstart

import forgecad as fc

# Connects to localhost:8765 by default
# Set FORGE_ENDPOINT to point at a remote server
doc = fc.Document()

# All API methods are available as Python methods
box = doc.add_box(width=50, depth=30, height=20)
box.fillet(radius=2)

props = doc.mass_properties()
print(f"Volume: {props.volume:.2f} mm³")

doc.export("output.step")

Method index

Document

Method	Params	Returns	Description
`document.create`	`{ title?: string }`	`DocumentRef`	Create a new empty document.
`document.open`	`{ path: string }`	`DocumentRef`	Open a .sfc or STEP/IGES file from disk.
`document.save`	`{ id: string, path?: string }`	`void`	Save the document. If path is omitted, overwrites the source file.
`document.export`	`{ id: string, path: string, format: string }`	`void`	Export to STEP, IGES, DXF, PDF, or SVG.
`document.close`	`{ id: string }`	`void`	Close and release a document.

Parameters

Method	Params	Returns	Description
`params.set`	`{ id: string, name: string, value: number }`	`void`	Set a named parameter. Triggers a rebuild if the document is parametric.
`params.get`	`{ id: string, name: string }`	`number`	Get the current value of a named parameter.
`params.list`	`{ id: string }`	`Param[]`	List all parameters and their current values.

Geometry

Method	Params	Returns	Description
`geometry.add_box`	`{ id: string, width: number, depth: number, height: number }`	`FeatureRef`	Add a parametric box.
`geometry.add_cylinder`	`{ id: string, radius: number, height: number }`	`FeatureRef`	Add a parametric cylinder.
`geometry.add_sphere`	`{ id: string, radius: number }`	`FeatureRef`	Add a sphere.
`geometry.boolean_union`	`{ id: string, a: string, b: string }`	`FeatureRef`	Boolean union of two bodies.
`geometry.boolean_cut`	`{ id: string, base: string, tool: string }`	`FeatureRef`	Subtract tool from base.
`geometry.boolean_intersect`	`{ id: string, a: string, b: string }`	`FeatureRef`	Intersection of two bodies.
`geometry.fillet`	`{ id: string, feature: string, radius: number, edges?: string[] }`	`void`	Apply a fillet. If edges is omitted, all edges are filleted.
`geometry.chamfer`	`{ id: string, feature: string, distance: number, edges?: string[] }`	`void`	Apply a chamfer.
`geometry.shell`	`{ id: string, feature: string, thickness: number, open_faces?: string[] }`	`void`	Shell a solid body.

Analysis

Method	Params	Returns	Description
`analysis.mass_properties`	`{ id: string, feature?: string }`	`MassProperties`	Compute volume, surface area, centre of mass, and moments of inertia.
`analysis.bounding_box`	`{ id: string, feature?: string }`	`BoundingBox`	Axis-aligned bounding box.
`analysis.interference`	`{ id: string, a: string, b: string }`	`InterferenceResult`	Check whether two bodies interfere.

Events

Method	Params	Returns	Description
`events.subscribe`	`{ events: string[] }`	`void`	Subscribe to document events over the WebSocket connection.
`events.unsubscribe`	`{ events: string[] }`	`void`	Unsubscribe from events.

Error codes

Code	Meaning
`-32700`	Parse error — invalid JSON
`-32600`	Invalid request
`-32601`	Method not found
`-32602`	Invalid params
`-32603`	Internal error
`-32001`	Document not found
`-32002`	Feature not found
`-32003`	Boolean operation failed — geometry may be degenerate
`-32004`	Rebuild failed — check parameter constraints
`-32010`	Licence error — feature requires Studio or Pro

The complete 413-line API reference (including CAM, FEA, drawing, assembly, and AI methods) is available in the ForgeCAD repository at forge_docs/api_reference.md. The methods above cover the core geometry and document operations.