GET /api/v1/faces

operationId: listFaces

Lists each face with its shell-request index and stable application-owned ID. Use topology=exact to list analytic faces on supported plain full-turn sketch revolves without changing the default mesh listing. Face IDs can be used as faceColors keys in PATCH /api/v1/shapes.

Authentication

Provide either authentication method:

• Bearer token (Authorization: Bearer <token>).
• API token in the X-SketchForge-Token header.

Parameters

Name	In	Required	Schema	Description
projectId	query	Yes	{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_-]*$","maxLength":120}	Whitespace is trimmed before validation. ID starts with a letter or digit and contains only letters, digits, underscores, and hyphens.
shapeId	query	Yes	{"type":"string","minLength":1}	Whitespace is trimmed; the remaining value must not be empty.
topology	query	No	{"type":"string","pattern":"^(mesh|exact)$"}	Optional. Use exact to list analytic B-rep faces on a supported plain full-turn sketch revolve; the default mesh listing keeps its existing indexes.

Request body

No request body.

Responses

200 — Successful response.

Content type: application/json

{
  "type": "object",
  "required": [
    "faces"
  ],
  "properties": {
    "faces": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "index",
          "id",
          "surfaceType",
          "area",
          "centroid",
          "normal",
          "facing"
        ],
        "properties": {
          "index": {
            "type": "integer",
            "minimum": 0,
            "description": "Zero-based index used by shell requests."
          },
          "id": {
            "type": "string",
            "description": "Application-owned face ID; use it as the faceColors key in PATCH /api/v1/shapes."
          },
          "surfaceType": {
            "type": "string",
            "description": "Surface kind reported by the CAD kernel, or unknown when unavailable."
          },
          "area": {
            "type": "number",
            "minimum": 0
          },
          "centroid": {
            "type": "object",
            "required": [
              "x",
              "y",
              "z"
            ],
            "properties": {
              "x": {
                "type": "number"
              },
              "y": {
                "type": "number"
              },
              "z": {
                "type": "number"
              }
            },
            "additionalProperties": false
          },
          "normal": {
            "type": [
              "object",
              "null"
            ],
            "required": [
              "x",
              "y",
              "z"
            ],
            "properties": {
              "x": {
                "type": "number"
              },
              "y": {
                "type": "number"
              },
              "z": {
                "type": "number"
              }
            },
            "additionalProperties": false
          },
          "facing": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "top",
              "bottom",
              "right",
              "left",
              "front",
              "back",
              null
            ]
          }
        },
        "additionalProperties": false
      }
    }
  },
  "additionalProperties": false
}

400 — Invalid request.

Content type: application/json

{
  "type": "object",
  "required": [
    "error",
    "code"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "invalid_project_id",
        "invalid_shape_id",
        "invalid_request"
      ]
    }
  },
  "additionalProperties": false
}

401 — Authentication failed.

Content type: application/json

{
  "type": "object",
  "required": [
    "error",
    "code"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "unauthorized"
      ]
    }
  },
  "additionalProperties": false
}

404 — Resource not found or API disabled.

Content type: application/json

{
  "type": "object",
  "required": [
    "error",
    "code"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "api_disabled",
        "project_not_found",
        "shape_not_found"
      ]
    }
  },
  "additionalProperties": false
}

422 — Request is valid JSON but cannot be applied.

Content type: application/json

{
  "type": "object",
  "required": [
    "error",
    "code"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "cad_failed"
      ]
    }
  },
  "additionalProperties": false
}

500 — Server-side failure.

Content type: application/json

{
  "type": "object",
  "required": [
    "error",
    "code"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "cad_failed",
        "internal_error"
      ]
    }
  },
  "additionalProperties": false
}

503 — Server-side failure.

Content type: application/json

{
  "type": "object",
  "required": [
    "error",
    "code"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "storage_unconfigured"
      ]
    }
  },
  "additionalProperties": false
}

Source

Route handler source · OpenAPI JSON · REST API guide

---

Documentation version: 1.30.0 · Repository revision: 1cb9fee8dff4d394684c229dd67a21da539d167f · View source