POST /api/v1/imports
operationId: importGeometry
Imports an STL, OBJ, or SVG file from base64 JSON or multipart form data, stores the source asset, and returns the imported mesh summary. Requests and decoded files are size-limited and return 413 limit_exceeded when over the supported limit.
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": [
"fileName"
],
"properties": {
"fileName": {
"type": "string",
"minLength": 1,
"pattern": "\\S",
"description": "File name is trimmed, selects the importer, and names the stored asset."
},
"data": {
"type": "string",
"minLength": 1,
"description": "Base64-encoded file bytes. Takes precedence over contents when both are sent."
},
"contents": {
"type": "string",
"minLength": 1,
"description": "Alias for data; used when data is absent."
},
"mediaType": {
"type": "string"
}
},
"anyOf": [
{
"type": "object",
"required": [
"data"
]
},
{
"type": "object",
"required": [
"contents"
]
}
],
"additionalProperties": true
}multipart/form-data
json
{
"type": "object",
"required": [
"file"
],
"properties": {
"file": {
"type": "string",
"description": "The uploaded model file.",
"format": "binary"
},
"fileName": {
"type": "string",
"minLength": 1,
"pattern": "\\S",
"description": "Optional trimmed importer name override; defaults to the uploaded file name."
}
},
"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"
},
"revision": {
"type": "number"
}
},
"additionalProperties": false
}400 — Invalid request.
Content type: application/json
json
{
"type": "object",
"required": [
"error",
"code"
],
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"invalid_project_id",
"invalid_body",
"invalid_request"
]
}
},
"additionalProperties": false
}401 — Authentication failed.
Content type: application/json
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
json
{
"type": "object",
"required": [
"error",
"code"
],
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"api_disabled",
"project_not_found"
]
}
},
"additionalProperties": false
}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": [
"project_busy",
"revision_mismatch"
]
},
"revision": {
"type": "number"
}
},
"additionalProperties": false
}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": [
"limit_exceeded"
]
},
"limit": {
"type": "integer"
},
"given": {
"type": "integer"
}
},
"additionalProperties": false
}415 — Response declared by the operation contract.
Content type: application/json
json
{
"type": "object",
"required": [
"error",
"code"
],
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"unsupported_format"
]
}
},
"additionalProperties": false
}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": [
"geometry_failed"
]
}
},
"additionalProperties": false
}500 — Server-side failure.
Content type: application/json
json
{
"type": "object",
"required": [
"error",
"code"
],
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string",
"enum": [
"internal_error"
]
}
},
"additionalProperties": false
}503 — Server-side failure.
Content type: application/json
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