Documentation

Workspace

Read-only project drawings, components, toolpaths, library resources, and bounded previews for companion clients.

Playground

Send these requests to your own running sidecar. Values stay in this browser.

Not connected

Base URL Bearer token optional Session token optional

How this works

The sidecar listens on a loopback port chosen at startup and prints it in its ready line; use that URL and the CADCAMFUN_TOKEN it was started with. Requests go straight from this page to that address.

The sidecar sends CORS headers only to the Tauri origins and to http://localhost or http://127.0.0.1 on any port. From the hosted docs the browser blocks the response, so run the docs locally (bun run dev in packages/web) to use the playground, or copy the request as curl. To experiment without touching real data, start the sidecar with CADCAMFUN_DATA_DIR pointed at a throwaway directory — see the API walkthrough.

Operations

8 endpoints in the workspace group, generated from the sidecar's own OpenAPI document. Protected operations take Authorization: Bearer $CADCAMFUN_TOKEN; see authentication. Behaviour and limits are in the subsystem guide.

get	/api/projects/{id}/workspace/drawings	workspace.drawings
get	/api/projects/{id}/workspace/drawings/{drawingId}/preview	workspace.drawingPreview
get	/api/projects/{id}/workspace/components	workspace.components
get	/api/projects/{id}/workspace/components/{componentId}/preview	workspace.componentPreview
get	/api/projects/{id}/workspace/toolpaths	workspace.toolpaths
get	/api/projects/{id}/workspace/toolpaths/{toolpathId}	workspace.toolpath
get	/api/projects/{id}/workspace/toolpaths/{toolpathId}/preview	workspace.toolpathPreview
get	/api/projects/{id}/workspace/library	workspace.library

Workspace operations in 3D Drag to orbit · scroll to zoom · right-drag to pan

One block per operation (8), stacked per resource section of this page and coloured by method: green GET, orange POST, blue PUT, violet PATCH, red DELETE. Generated from the OpenAPI document at build time.

/api/projects

get /api/projects/{id}/workspace/drawings # workspace.drawings

Requires Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
id	path	string	required

Responses

200 Array<object> application/json

Array<{
  id: string
  name: string
  subtitle: string | null
  updatedAt: string
}>

400 BadRequestEncoded application/json

BadRequestEncoded

401 UnauthorizedEncoded application/json

UnauthorizedEncoded

404 NotFoundEncoded application/json

NotFoundEncoded

500 InternalErrorEncoded application/json

InternalErrorEncoded

fetch example

workspace.drawings

// Not generated in the Promise SDK (multipart, binary or raw body): call it with fetch.
const response = await fetch(`${process.env.CADCAMFUN_URL}/api/projects/${id}/workspace/drawings`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.CADCAMFUN_TOKEN}` },
})

curl

GET /api/projects/{id}/workspace/drawings

curl --request GET "${CADCAMFUN_URL}/api/projects/<id>/workspace/drawings" \
  --header "Authorization: Bearer ${CADCAMFUN_TOKEN}"

Try it

id path · required

get /api/projects/{id}/workspace/drawings/{drawingId}/preview # workspace.drawingPreview

Requires Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
id	path	string	required
drawingId	path	string	required

Responses

200 object application/json

{
  positions: Array<number | "Infinity" | "-Infinity" | "NaN">
  indices: Array<number | "Infinity" | "-Infinity" | "NaN">
  normals: Array<number | "Infinity" | "-Infinity" | "NaN">
  bounds: {
    min: unknown[]
    max: unknown[]
  }
  parts: Array<{
    id: string
    name: string
    triangleStart: number | "Infinity" | "-Infinity" | "NaN"
    triangleCount: number | "Infinity" | "-Infinity" | "NaN"
  }>
  truncated: boolean
  revision: string
  features?: Array<{
    elementId: string
    name: string
    features: Array<{
      id: string
      type: string
      parameters: Array<{
        key: string
        value: string
      }>
    }>
  }>
}

400 BadRequestEncoded application/json

BadRequestEncoded

401 UnauthorizedEncoded application/json

UnauthorizedEncoded

404 NotFoundEncoded application/json

NotFoundEncoded

500 InternalErrorEncoded application/json

InternalErrorEncoded

fetch example

workspace.drawingPreview

// Not generated in the Promise SDK (multipart, binary or raw body): call it with fetch.
const response = await fetch(`${process.env.CADCAMFUN_URL}/api/projects/${id}/workspace/drawings/${drawingId}/preview`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.CADCAMFUN_TOKEN}` },
})

curl

GET /api/projects/{id}/workspace/drawings/{drawingId}/preview

curl --request GET "${CADCAMFUN_URL}/api/projects/<id>/workspace/drawings/<drawingId>/preview" \
  --header "Authorization: Bearer ${CADCAMFUN_TOKEN}"

Try it

id path · required drawingId path · required

get /api/projects/{id}/workspace/components # workspace.components

Requires Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
id	path	string	required

Responses

200 Array<object> application/json

Array<{
  id: string
  name: string
  subtitle: string | null
  updatedAt: string
}>

400 BadRequestEncoded application/json

BadRequestEncoded

401 UnauthorizedEncoded application/json

UnauthorizedEncoded

404 NotFoundEncoded application/json

NotFoundEncoded

500 InternalErrorEncoded application/json

InternalErrorEncoded

fetch example

workspace.components

// Not generated in the Promise SDK (multipart, binary or raw body): call it with fetch.
const response = await fetch(`${process.env.CADCAMFUN_URL}/api/projects/${id}/workspace/components`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.CADCAMFUN_TOKEN}` },
})

curl

GET /api/projects/{id}/workspace/components

curl --request GET "${CADCAMFUN_URL}/api/projects/<id>/workspace/components" \
  --header "Authorization: Bearer ${CADCAMFUN_TOKEN}"

Try it

id path · required

get /api/projects/{id}/workspace/components/{componentId}/preview # workspace.componentPreview

Requires Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
id	path	string	required
componentId	path	string	required

Responses

200 object application/json

{
  positions: Array<number | "Infinity" | "-Infinity" | "NaN">
  indices: Array<number | "Infinity" | "-Infinity" | "NaN">
  normals: Array<number | "Infinity" | "-Infinity" | "NaN">
  bounds: {
    min: unknown[]
    max: unknown[]
  }
  parts: Array<{
    id: string
    name: string
    triangleStart: number | "Infinity" | "-Infinity" | "NaN"
    triangleCount: number | "Infinity" | "-Infinity" | "NaN"
  }>
  truncated: boolean
  revision: string
  features?: Array<{
    elementId: string
    name: string
    features: Array<{
      id: string
      type: string
      parameters: Array<{
        key: string
        value: string
      }>
    }>
  }>
  parameters: Array<{
    key: string
    value: string
  }>
}

400 BadRequestEncoded application/json

BadRequestEncoded

401 UnauthorizedEncoded application/json

UnauthorizedEncoded

404 NotFoundEncoded application/json

NotFoundEncoded

500 InternalErrorEncoded application/json

InternalErrorEncoded

fetch example

workspace.componentPreview

// Not generated in the Promise SDK (multipart, binary or raw body): call it with fetch.
const response = await fetch(`${process.env.CADCAMFUN_URL}/api/projects/${id}/workspace/components/${componentId}/preview`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.CADCAMFUN_TOKEN}` },
})

curl

GET /api/projects/{id}/workspace/components/{componentId}/preview

curl --request GET "${CADCAMFUN_URL}/api/projects/<id>/workspace/components/<componentId>/preview" \
  --header "Authorization: Bearer ${CADCAMFUN_TOKEN}"

Try it

id path · required componentId path · required

get /api/projects/{id}/workspace/toolpaths # workspace.toolpaths

Requires Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
id	path	string	required

Responses

200 Array<object> application/json

Array<{
  id: string
  name: string
  subtitle: string | null
  updatedAt: string
}>

400 BadRequestEncoded application/json

BadRequestEncoded

401 UnauthorizedEncoded application/json

UnauthorizedEncoded

404 NotFoundEncoded application/json

NotFoundEncoded

500 InternalErrorEncoded application/json

InternalErrorEncoded

fetch example

workspace.toolpaths

// Not generated in the Promise SDK (multipart, binary or raw body): call it with fetch.
const response = await fetch(`${process.env.CADCAMFUN_URL}/api/projects/${id}/workspace/toolpaths`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.CADCAMFUN_TOKEN}` },
})

curl

GET /api/projects/{id}/workspace/toolpaths

curl --request GET "${CADCAMFUN_URL}/api/projects/<id>/workspace/toolpaths" \
  --header "Authorization: Bearer ${CADCAMFUN_TOKEN}"

Try it

id path · required

get /api/projects/{id}/workspace/toolpaths/{toolpathId} # workspace.toolpath

Requires Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
id	path	string	required
toolpathId	path	string	required

Responses

200 object application/json

{
  id: string
  name: string
  operationType: string | null
  gcode: string
  stats: {
    rapidMoves: number | "Infinity" | "-Infinity" | "NaN"
    linearMoves: number | "Infinity" | "-Infinity" | "NaN"
    circularMoves: number | "Infinity" | "-Infinity" | "NaN"
    machineFunctions: number | "Infinity" | "-Infinity" | "NaN"
  }
  revision: string
  updatedAt: string
}

400 BadRequestEncoded application/json

BadRequestEncoded

401 UnauthorizedEncoded application/json

UnauthorizedEncoded

404 NotFoundEncoded application/json

NotFoundEncoded

500 InternalErrorEncoded application/json

InternalErrorEncoded

fetch example

workspace.toolpath

// Not generated in the Promise SDK (multipart, binary or raw body): call it with fetch.
const response = await fetch(`${process.env.CADCAMFUN_URL}/api/projects/${id}/workspace/toolpaths/${toolpathId}`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.CADCAMFUN_TOKEN}` },
})

curl

GET /api/projects/{id}/workspace/toolpaths/{toolpathId}

curl --request GET "${CADCAMFUN_URL}/api/projects/<id>/workspace/toolpaths/<toolpathId>" \
  --header "Authorization: Bearer ${CADCAMFUN_TOKEN}"

Try it

id path · required toolpathId path · required

get /api/projects/{id}/workspace/toolpaths/{toolpathId}/preview # workspace.toolpathPreview

Requires Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
id	path	string	required
toolpathId	path	string	required

Responses

200 object application/json

{
  segments: Array<{
    kind: "rapid" | "linear" | "circular"
    line: number | "Infinity" | "-Infinity" | "NaN"
    from: unknown[]
    to: unknown[]
  }>
  bounds: {
    min: unknown[]
    max: unknown[]
  }
  stock: {
    min: unknown[]
    max: unknown[]
  }
  truncated: boolean
  stats: {
    rapidMoves: number | "Infinity" | "-Infinity" | "NaN"
    linearMoves: number | "Infinity" | "-Infinity" | "NaN"
    circularMoves: number | "Infinity" | "-Infinity" | "NaN"
    machineFunctions: number | "Infinity" | "-Infinity" | "NaN"
  }
  machine?: {
    kind: "mill" | "lathe" | "3dprinter"
    source: "override" | "kernel" | "generator" | "inferred" | "settings"
    mismatch?: {
      inferred: "mill" | "lathe" | "3dprinter"
      reasons: string[]
    }
    axes: number | "Infinity" | "-Infinity" | "NaN"
    turns: string
    workholding: string
    assumed: Array<"workholding" | "table" | "stock">
    xMode?: "diameter" | "radius"
    turret?: "rear" | "front"
    bodies: Array<{
      id: string
      role: "stock" | "jaw" | "parallel" | "vise-base" | "clamp" | "table" | "chuck" | "collet" | "tailstock" | "bed" | "build-volume"
      shape: {
        type: "box"
        min: {
          x: number | "Infinity" | "-Infinity" | "NaN"
          y: number | "NaN"
          z: number | "NaN"
        }
        max: {
          x: number | "NaN"
        }
      } | {
        type: "cylinder-x"
        x0: number | "NaN"
        x1: number | "NaN"
        radius: number | "NaN"
        inner: number | "NaN"
      } | {
        type: "cone-x"
        x0: number | "NaN"
        r0: number | "NaN"
        r1: number
      rotateX?: number | "Infinity" | "-Infinity" | "NaN"
      spins: boolean
      assumed: boolean
      obstacle: boolean
      wire?: boolean
    }>
    spin: Array<{
      segment: number | "Infinity" | "-Infinity" | "NaN"
      rate: number | "Infinity" | "-Infinity" | "NaN"
    }>
    collisions: Array<number | "Infinity" | "-Infinity" | "NaN">
    operations?: Array<{
      index: number | "Infinity" | "-Infinity" | "NaN"
      name: string
      toolId: string
      startSegment: number | "Infinity" | "-Infinity" | "NaN"
      endSegment: number | "Infinity" | "-Infinity" | "NaN"
      cutter?: {
        diameter: number | "Infinity" | "-Infinity" | "NaN"
        fluteLength: number | "Infinity" | "-Infinity" | "NaN"
        shankDiameter: number | "Infinity" | "-Infinity" | "NaN"
        stickout: number | "Infinity" | "-Infinity" | "NaN"
        noseRadius: number | "Infinity" | "-Infinity" | "NaN"
        holder: {
          diameter: number | "Infinity" | "-Infinity" | "NaN"
          length: number | "Infinity" | "-Infinity" | "NaN"
          kind: string
          assumed: boolean
        }
      }
    }>
    events?: Array<{
      code: string
      severity: "error" | "warning"
      seconds: number | "Infinity" | "-Infinity" | "NaN"
      segment: number | "Infinity" | "-Infinity" | "NaN"
      line?: number | "Infinity" | "-Infinity" | "NaN"
      message: string
    }>
    tool: {
      family: "mill" | "lathe" | "nozzle"
      diameter: number | "Infinity" | "-Infinity" | "NaN"
      width: number | "Infinity" | "-Infinity" | "NaN"
      noseRadius: number | "Infinity" | "-Infinity" | "NaN"
      insert: string
      internal: boolean
      turret?: "rear" | "front"
    }
  }
  part?: {
    positions: Array<number | "Infinity" | "-Infinity" | "NaN">
    indices: Array<number | "Infinity" | "-Infinity" | "NaN">
    normals: Array<number | "Infinity" | "-Infinity" | "NaN">
    bounds: {
      min: unknown[]
      max: unknown[]
    }
    parts: Array<{
      id: string
      name: string
      triangleStart: number | "Infinity" | "-Infinity" | "NaN"
      triangleCount: number | "Infinity" | "-Infinity" | "NaN"
    }>
    truncated: boolean
  }
  revision: string
}

400 BadRequestEncoded application/json

BadRequestEncoded

401 UnauthorizedEncoded application/json

UnauthorizedEncoded

404 NotFoundEncoded application/json

NotFoundEncoded

500 InternalErrorEncoded application/json

InternalErrorEncoded

fetch example

workspace.toolpathPreview

// Not generated in the Promise SDK (multipart, binary or raw body): call it with fetch.
const response = await fetch(`${process.env.CADCAMFUN_URL}/api/projects/${id}/workspace/toolpaths/${toolpathId}/preview`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.CADCAMFUN_TOKEN}` },
})

curl

GET /api/projects/{id}/workspace/toolpaths/{toolpathId}/preview

curl --request GET "${CADCAMFUN_URL}/api/projects/<id>/workspace/toolpaths/<toolpathId>/preview" \
  --header "Authorization: Bearer ${CADCAMFUN_TOKEN}"

Try it

id path · required toolpathId path · required

get /api/projects/{id}/workspace/library # workspace.library

Requires Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
id	path	string	required

Responses

200 object application/json

{
  materials: Array<{
    id: string
    name: string
    subtitle: string | null
    updatedAt: string
  }>
  tools: Array<{
    id: string
    name: string
    subtitle: string | null
    updatedAt: string
  }>
  machines: Array<{
    id: string
    name: string
    subtitle: string | null
    updatedAt: string
  }>
  components: Array<{
    id: string
    name: string
    subtitle: string | null
    updatedAt: string
  }>
}

400 BadRequestEncoded application/json

BadRequestEncoded

401 UnauthorizedEncoded application/json

UnauthorizedEncoded

404 NotFoundEncoded application/json

NotFoundEncoded

500 InternalErrorEncoded application/json

InternalErrorEncoded

fetch example

workspace.library

// Not generated in the Promise SDK (multipart, binary or raw body): call it with fetch.
const response = await fetch(`${process.env.CADCAMFUN_URL}/api/projects/${id}/workspace/library`, {
  method: "GET",
  headers: { authorization: `Bearer ${process.env.CADCAMFUN_TOKEN}` },
})

curl

GET /api/projects/{id}/workspace/library

curl --request GET "${CADCAMFUN_URL}/api/projects/<id>/workspace/library" \
  --header "Authorization: Bearer ${CADCAMFUN_TOKEN}"

Try it

id path · required

Schemas

Named schemas reachable from this group's parameters, bodies and responses. A ? marks an optional field; | null marks a field that may be present with a null value.

BadRequestEncoded

{
  _tag: "BadRequest"
  message: string
}

InternalErrorEncoded

{
  _tag: "InternalError"
  message: string
}

NotFoundEncoded

{
  _tag: "NotFound"
  message: string
}

UnauthorizedEncoded

{
  _tag: "Unauthorized"
  message: string
}

Calling this group

Operation ids have the form workspace.<name>. The generated Promise SDK (@cadcamfun/api/sdk) exposes most of them as client.<namespace>.<method>(input), where input is one flat object of path parameters and body fields; each card's SDK example shows the exact accessor and input type. Multipart uploads, binary or JavaScript responses and raw webhooks are not generated; those cards show fetch instead.

Errors from the Promise SDK

import { CadCam, ClientError } from "@cadcamfun/api/sdk"

const client = CadCam.make({
  baseUrl: process.env.CADCAMFUN_URL!,
  headers: { authorization: `Bearer ${process.env.CADCAMFUN_TOKEN}` },
})

try {
  await client.projects.list()
} catch (error) {
  if (error instanceof ClientError) {
    // Transport | UnexpectedStatus | UnsupportedContentType | MalformedResponse | SseEventTooLarge
  } else {
    // a declared error body: switch on error._tag
  }
}

Troubleshooting

Symptom	Likely cause	Fix
401 on every call	Token from a previous launch, or missing `Bearer` prefix	Send `Authorization: Bearer <token>` with the token the sidecar was started with.
400 before anything happens	Body or parameter does not match the schema	Compare the payload with the request schema on the card.
403 or 404 on a record you can see elsewhere	The acting account differs	Send the right `x-session-token`, or use the local profile that owns the record.
409	Conflicting state, such as a duplicate name or a stale branch head	Re-read the resource and retry with current data.
Try it says "blocked by CORS"	The docs are served from a non-loopback origin	Run the docs locally or copy the request as curl.
Connection refused	The sidecar restarted on a new port	Read the port from the new `ready` line.