POST /api/v1/booleans
operationId: booleanShapes
Subtract one or more cutter shapes, including helical thread meshes, from solids and persist exact geometry. Kernel geometry failures return 422 geometry_failed.
Authentication
Provide either authentication method:
- Bearer token (
Authorization: Bearer <token>). - API token in the
X-SketchForge-Tokenheader.
Parameters
| Name | In | Required | Schema | Description |
|---|---|---|---|---|
projectId | query | Yes | {"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]*$","maxLength":120} | — |
If-Match | header | No | {"type":"string","pattern":"^\\\"[0-9]+\\\"$"} | Apply this write only when the project still has the quoted revision returned by a previous write. A mismatch returns 409 revision_mismatch with the current revision. |
Request body
Required.
application/json
json
{
"type": "object",
"required": [
"solidIds",
"holeIds"
],
"properties": {
"solidIds": {
"oneOf": [
{
"type": "string",
"pattern": "\\S"
},
{
"type": "array",
"minItems": 1,
"items": {
"type": "string",
"pattern": "\\S"
}
}
]
},
"holeIds": {
"oneOf": [
{
"type": "string",
"pattern": "\\S"
},
{
"type": "array",
"minItems": 1,
"items": {
"type": "string",
"pattern": "\\S"
}
}
]
}
},
"additionalProperties": true
}Responses
201 — Resource created.
Headers:
json
{
"ETag": {
"description": "The project revision after this write.",
"schema": {
"type": "string",
"pattern": "^\\\"[0-9]+\\\"$"
}
}
}Content type: application/json
json
{
"type": "object",
"required": [
"shape",
"triangles",
"revision"
],
"properties": {
"shape": {
"type": "object",
"required": [
"id",
"name",
"kind",
"color",
"hole",
"locked",
"hidden",
"x",
"z",
"elevation",
"width",
"depth",
"rotation",
"rotationX",
"rotationZ"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"kind": {
"type": "string"
},
"requestKind": {
"type": "string"
},
"sketchOperation": {
"type": "string"
},
"sketchSourceId": {
"type": "string"
},
"draftPrismAngle": {
"type": "number"
},
"faceDraft": {
"type": "object",
"required": [
"sourceFaceId",
"angle",
"pullDirection",
"sourceFaceNormal"
],
"properties": {
"sourceFaceId": {
"type": "string"
},
"angle": {
"type": "number"
},
"pullDirection": {
"type": "string",
"enum": [
"x",
"y",
"z",
"-x",
"-y",
"-z"
]
},
"sourceFaceNormal": {
"type": "object",
"required": [
"x",
"y",
"z"
],
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
},
"z": {
"type": "number"
}
}
}
}
},
"sketchProfile": {
"type": "object",
"required": [
"points",
"segments"
],
"properties": {
"points": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"segments": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"sweepFrames": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": true
},
"color": {
"type": "string"
},
"faceIds": {
"type": "array",
"items": {
"type": "string"
}
},
"faceColors": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"stepAssembly": {
"type": "array",
"description": "Optional STEP product hierarchy metadata. Imported geometry remains one mesh until exploded.",
"items": {
"type": "object",
"required": [
"name",
"children"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"children": {
"type": "array",
"maxItems": 2000,
"description": "Direct product children; hierarchy depth is capped at 32.",
"items": {
"type": "object",
"required": [
"name",
"children"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"children": {
"type": "array",
"maxItems": 2000,
"description": "Direct product children; hierarchy depth is capped at 32.",
"items": {
"type": "object",
"required": [
"name",
"children"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"children": {
"type": "array",
"maxItems": 2000,
"description": "Direct product children; hierarchy depth is capped at 32.",
"items": {
"type": "object",
"required": [
"name",
"children"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"children": {
"type": "array",
"maxItems": 2000,
"description": "Direct product children; hierarchy depth is capped at 32.",
"items": {
"type": "object",
"required": [
"name",
"children"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"children": {
"type": "array",
"maxItems": 2000,
"description": "Direct product children; hierarchy depth is capped at 32.",
"items": {
"type": "object",
"required": [
"name",
"children"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"children": {
"type": "array",
"maxItems": 2000,
"description": "Direct product children; hierarchy depth is capped at 32.",
"items": {
"type": "object",
"required": [
"name",
"children"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"children": {
"type": "array",
"maxItems": 2000,
"description": "Direct product children; hierarchy depth is capped at 32.",
"items": {
"type": "object",
"required": [
"name",
"children"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"children": {
"type": "array",
"maxItems": 2000,
"description": "Direct product children; hierarchy depth is capped at 32.",
"items": {
"type": "object",
"required": [
"name",
"children"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"children": {
"type": "array",
"maxItems": 2000,
"description": "Direct product children; hierarchy depth is capped at 32.",
"items": {
"type": "object",
"required": [
"name",
"children"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"children": {
"type": "array",
"maxItems": 2000,
"description": "Direct product children; hierarchy depth is capped at 32.",
"items": {
"type": "object",
"required": [
"name",
"children"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"children": {
"type": "array",
"maxItems": 2000,
"description": "Direct product children; hierarchy depth is capped at 32.",
"items": {
"type": "object",
"required": [
"name",
"children"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"children": {
"type": "array",
"maxItems": 2000,
"description": "Direct product children; hierarchy depth is capped at 32.",
"items": {
"type": "object",
"required": [
"name",
"children"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"children": {
"type": "array",
"maxItems": 2000,
"description": "Direct product children; hierarchy depth is capped at 32.",
"items": {
"type": "object",
"required": [
"name",
"children"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"children": {
"type": "array",
"maxItems": 2000,
"description": "Direct product children; hierarchy depth is capped at 32.",
"items": {
"type": "object",
"required": [
"name",
"children"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"children": {
"type": "array",
"maxItems": 2000,
"description": "Direct product children; hierarchy depth is capped at 32.",
"items": {
"type": "object",
"required": [
"name",
"children"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"children": {
"type": "array",
"maxItems": 2000,
"description": "Direct product children; hierarchy depth is capped at 32.",
"items": {
"type": "object",
"required": [
"name",
"children"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"children": {
"type": "array",
"maxItems": 2000,
"description": "Direct product children; hierarchy depth is capped at 32.",
"items": {
"type": "object",
"required": [
"name",
"children"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"children": {
"type": "array",
"maxItems": 2000,
"description": "Direct product children; hierarchy depth is capped at 32.",
"items": {
"type": "object",
"required": [
"name",
"children"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"children": {
"type": "array",
"maxItems": 2000,
"description": "Direct product children; hierarchy depth is capped at 32.",
"items": {
"type": "object",
"required": [
"name",
"children"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"children": {
"type": "array",
"maxItems": 2000,
"description": "Direct product children; hierarchy depth is capped at 32.",
"items": {
"type": "object",
"required": [
"name",
"children"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"children": {
"type": "array",
"maxItems": 2000,
"description": "Direct product children; hierarchy depth is capped at 32.",
"items": {
"type": "object",
"required": [
"name",
"children"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"children": {
"type": "array",
"maxItems": 2000,
"description": "Direct product children; hierarchy depth is capped at 32.",
"items": {
"type": "object",
"required": [
"name",
"children"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"children": {
"type": "array",
"maxItems": 2000,
"description": "Direct product children; hierarchy depth is capped at 32.",
"items": {
"type": "object",
"required": [
"name",
"children"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"children": {
"type": "array",
"maxItems": 2000,
"description": "Direct product children; hierarchy depth is capped at 32.",
"items": {
"type": "object",
"required": [
"name",
"children"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"children": {
"type": "array",
"maxItems": 2000,
"description": "Direct product children; hierarchy depth is capped at 32.",
"items": {
"type": "object",
"required": [
"name",
"children"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"children": {
"type": "array",
"maxItems": 2000,
"description": "Direct product children; hierarchy depth is capped at 32.",
"items": {
"type": "object",
"required": [
"name",
"children"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"children": {
"type": "array",
"maxItems": 2000,
"description": "Direct product children; hierarchy depth is capped at 32.",
"items": {
"type": "object",
"required": [
"name",
"children"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"children": {
"type": "array",
"maxItems": 2000,
"description": "Direct product children; hierarchy depth is capped at 32.",
"items": {
"type": "object",
"required": [
"name",
"children"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"children": {
"type": "array",
"maxItems": 2000,
"description": "Direct product children; hierarchy depth is capped at 32.",
"items": {
"type": "object",
"required": [
"name",
"children"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"children": {
"type": "array",
"maxItems": 2000,
"description": "Direct product children; hierarchy depth is capped at 32.",
"items": {
"type": "object",
"required": [
"name",
"children"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"children": {
"type": "array",
"maxItems": 2000,
"description": "Direct product children; hierarchy depth is capped at 32.",
"items": {
"type": "object",
"required": [
"name",
"children"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"children": {
"type": "array",
"maxItems": 0,
"description": "Direct product children; hierarchy depth is capped at 32."
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
},
"stepComponent": {
"type": "object",
"required": [
"id",
"occurrenceId",
"path"
],
"description": "STEP source occurrence identity and root-to-component ancestry for a selectable exploded solid.",
"properties": {
"id": {
"type": "string"
},
"occurrenceId": {
"type": "string"
},
"path": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"hole": {
"type": "boolean"
},
"locked": {
"type": "boolean"
},
"hidden": {
"type": "boolean"
},
"x": {
"type": "number"
},
"z": {
"type": "number"
},
"elevation": {
"type": "number"
},
"width": {
"type": "number"
},
"depth": {
"type": "number"
},
"height": {
"type": "number"
},
"rotation": {
"type": "number"
},
"rotationX": {
"type": "number"
},
"rotationZ": {
"type": "number"
},
"groupedCount": {
"type": "integer"
},
"revolve": {
"type": "object",
"additionalProperties": true
},
"profile": {
"type": "array",
"items": {
"type": "array",
"minItems": 2,
"maxItems": 2,
"items": {
"type": "number"
}
}
}
}
},
"triangles": {
"type": "integer",
"minimum": 0
},
"revision": {
"type": "number"
}
}
}400 — Invalid request.
Content type: application/json
json
{
"type": "object",
"required": [
"error",
"code"
],
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"api_disabled",
"unauthorized",
"storage_unconfigured",
"invalid_project_id",
"invalid_shape_id",
"invalid_body",
"invalid_request",
"project_not_found",
"project_exists",
"project_busy",
"revision_mismatch",
"shape_not_found",
"shape_locked",
"unsupported_kind",
"unsupported_format",
"unapplicable_fields",
"too_many_shapes",
"limit_exceeded",
"geometry_failed",
"cad_failed",
"internal_error"
]
},
"revision": {
"type": "number"
}
},
"additionalProperties": true
}401 — Authentication failed.
Content type: application/json
json
{
"type": "object",
"required": [
"error",
"code"
],
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"api_disabled",
"unauthorized",
"storage_unconfigured",
"invalid_project_id",
"invalid_shape_id",
"invalid_body",
"invalid_request",
"project_not_found",
"project_exists",
"project_busy",
"revision_mismatch",
"shape_not_found",
"shape_locked",
"unsupported_kind",
"unsupported_format",
"unapplicable_fields",
"too_many_shapes",
"limit_exceeded",
"geometry_failed",
"cad_failed",
"internal_error"
]
},
"revision": {
"type": "number"
}
},
"additionalProperties": true
}404 — Resource not found or API disabled.
Content type: application/json
json
{
"type": "object",
"required": [
"error",
"code"
],
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"api_disabled",
"unauthorized",
"storage_unconfigured",
"invalid_project_id",
"invalid_shape_id",
"invalid_body",
"invalid_request",
"project_not_found",
"project_exists",
"project_busy",
"revision_mismatch",
"shape_not_found",
"shape_locked",
"unsupported_kind",
"unsupported_format",
"unapplicable_fields",
"too_many_shapes",
"limit_exceeded",
"geometry_failed",
"cad_failed",
"internal_error"
]
},
"revision": {
"type": "number"
}
},
"additionalProperties": true
}409 — The project is busy or the request conflicts with current state.
Content type: application/json
json
{
"type": "object",
"required": [
"error",
"code"
],
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"api_disabled",
"unauthorized",
"storage_unconfigured",
"invalid_project_id",
"invalid_shape_id",
"invalid_body",
"invalid_request",
"project_not_found",
"project_exists",
"project_busy",
"revision_mismatch",
"shape_not_found",
"shape_locked",
"unsupported_kind",
"unsupported_format",
"unapplicable_fields",
"too_many_shapes",
"limit_exceeded",
"geometry_failed",
"cad_failed",
"internal_error"
]
},
"revision": {
"type": "number"
}
},
"additionalProperties": true
}413 — Request exceeds the supported size or item limit.
Content type: application/json
json
{
"type": "object",
"required": [
"error",
"code"
],
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"api_disabled",
"unauthorized",
"storage_unconfigured",
"invalid_project_id",
"invalid_shape_id",
"invalid_body",
"invalid_request",
"project_not_found",
"project_exists",
"project_busy",
"revision_mismatch",
"shape_not_found",
"shape_locked",
"unsupported_kind",
"unsupported_format",
"unapplicable_fields",
"too_many_shapes",
"limit_exceeded",
"geometry_failed",
"cad_failed",
"internal_error"
]
},
"revision": {
"type": "number"
}
},
"additionalProperties": true
}422 — Request is valid JSON but cannot be applied.
Content type: application/json
json
{
"type": "object",
"required": [
"error",
"code"
],
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"api_disabled",
"unauthorized",
"storage_unconfigured",
"invalid_project_id",
"invalid_shape_id",
"invalid_body",
"invalid_request",
"project_not_found",
"project_exists",
"project_busy",
"revision_mismatch",
"shape_not_found",
"shape_locked",
"unsupported_kind",
"unsupported_format",
"unapplicable_fields",
"too_many_shapes",
"limit_exceeded",
"geometry_failed",
"cad_failed",
"internal_error"
]
},
"revision": {
"type": "number"
}
},
"additionalProperties": true
}500 — Server-side failure.
Content type: application/json
json
{
"type": "object",
"required": [
"error",
"code"
],
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"api_disabled",
"unauthorized",
"storage_unconfigured",
"invalid_project_id",
"invalid_shape_id",
"invalid_body",
"invalid_request",
"project_not_found",
"project_exists",
"project_busy",
"revision_mismatch",
"shape_not_found",
"shape_locked",
"unsupported_kind",
"unsupported_format",
"unapplicable_fields",
"too_many_shapes",
"limit_exceeded",
"geometry_failed",
"cad_failed",
"internal_error"
]
},
"revision": {
"type": "number"
}
},
"additionalProperties": true
}503 — Server-side failure.
Content type: application/json
json
{
"type": "object",
"required": [
"error",
"code"
],
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"api_disabled",
"unauthorized",
"storage_unconfigured",
"invalid_project_id",
"invalid_shape_id",
"invalid_body",
"invalid_request",
"project_not_found",
"project_exists",
"project_busy",
"revision_mismatch",
"shape_not_found",
"shape_locked",
"unsupported_kind",
"unsupported_format",
"unapplicable_fields",
"too_many_shapes",
"limit_exceeded",
"geometry_failed",
"cad_failed",
"internal_error"
]
},
"revision": {
"type": "number"
}
},
"additionalProperties": true
}Source
Route handler source · OpenAPI JSON · REST API guide
Documentation version: 1.30.0 · Repository revision: 1cb9fee8dff4d394684c229dd67a21da539d167f · View source