POST /api/v1/exports

operationId: exportProject

Export project geometry as JSON/base64, or return the raw artifact when download=1. Binary downloads carry result metadata in the X-SketchForge-Metadata response header. Section size caps return 413 limit_exceeded; geometry failures return 422.

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}	—
download	query	No	{"type":"string"}	Set download=1 to return raw artifact bytes; omitted or any other value returns JSON with base64 content.

Request body

Required.

application/json

{
  "type": "object",
  "required": [
    "format"
  ],
  "properties": {
    "format": {
      "type": "string",
      "enum": [
        "stl",
        "obj",
        "3mf",
        "step",
        "skf",
        "zip",
        "svg",
        "dxf"
      ]
    },
    "shapeIds": {
      "oneOf": [
        {
          "type": "string",
          "pattern": "\\S",
          "description": "A single non-empty shape ID is accepted as shorthand."
        },
        {
          "type": "array",
          "uniqueItems": true,
          "description": "IDs are trimmed and must be distinct after trimming.",
          "items": {
            "type": "string",
            "pattern": "\\S"
          }
        }
      ]
    },
    "name": {
      "type": "string",
      "maxLength": 120,
      "description": "Optional output basename; an empty or omitted value uses the project name."
    },
    "view": {
      "type": "string",
      "enum": [
        "multiview",
        "front",
        "back",
        "top",
        "bottom",
        "left",
        "right",
        "iso"
      ],
      "description": "SVG only; section and view are mutually exclusive."
    },
    "featureAngle": {
      "type": "number",
      "minimum": 0,
      "maximum": 180,
      "description": "SVG projection only: crease angle in degrees for mesh shapes. An edge between two triangles is drawn only where they meet at more than this, besides boundaries and silhouettes. Defaults to 30; exact solids ignore it."
    },
    "section": {
      "type": "object",
      "required": [
        "plane",
        "offset"
      ],
      "description": "SVG or DXF only; section and view are mutually exclusive.",
      "properties": {
        "plane": {
          "type": "string",
          "enum": [
            "xy",
            "xz",
            "yz"
          ]
        },
        "offset": {
          "type": "number",
          "minimum": -100000,
          "maximum": 100000,
          "description": "Finite section-plane coordinate in millimetres."
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": true
}

Responses

200 — Successful response.

Headers:

{
  "X-SketchForge-Metadata": {
    "description": "URI-encoded JSON containing the export metadata fields (format, filename, mimeType, shapeCount, and optional STEP skipped-shape details).",
    "schema": {
      "type": "string"
    }
  }
}

Content type: application/json

{
  "type": "object",
  "required": [
    "format",
    "filename",
    "mimeType",
    "bytes",
    "shapeCount",
    "base64"
  ],
  "properties": {
    "format": {
      "type": "string",
      "enum": [
        "stl",
        "obj",
        "3mf",
        "step",
        "skf",
        "zip",
        "svg",
        "dxf"
      ]
    },
    "filename": {
      "type": "string"
    },
    "mimeType": {
      "type": "string"
    },
    "shapeCount": {
      "type": "integer",
      "minimum": 0
    },
    "exportedCount": {
      "type": "integer",
      "minimum": 0
    },
    "skipped": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "name",
          "kind",
          "reason"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "reason": {
            "type": "string"
          }
        },
        "additionalProperties": false
      }
    },
    "bytes": {
      "type": "integer",
      "minimum": 0
    },
    "base64": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

Content type: model/stl

{
  "type": "string",
  "format": "binary"
}

Content type: text/plain

{
  "type": "string",
  "format": "binary"
}

Content type: model/3mf

{
  "type": "string",
  "format": "binary"
}

Content type: model/step

{
  "type": "string",
  "format": "binary"
}

Content type: application/vnd.sketchforge.project+zip

{
  "type": "string",
  "format": "binary"
}

Content type: application/zip

{
  "type": "string",
  "format": "binary"
}

Content type: image/svg+xml

{
  "type": "string",
  "format": "binary"
}

Content type: application/dxf

{
  "type": "string",
  "format": "binary"
}

400 — Invalid request.

Content type: application/json

{
  "type": "object",
  "required": [
    "error",
    "code"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "invalid_project_id",
        "invalid_body",
        "unsupported_format",
        "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
}

413 — Request exceeds the supported size or item limit.

Content type: application/json

{
  "type": "object",
  "required": [
    "error",
    "code"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string",
      "enum": [
        "limit_exceeded"
      ]
    },
    "limit": {
      "type": "integer"
    },
    "given": {
      "type": "integer"
    }
  },
  "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": [
        "geometry_failed"
      ]
    }
  },
  "additionalProperties": false
}

500 — Server-side failure.

Content type: application/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

{
  "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