Documentation

Toolpaths

Saved machining programs, drawing associations, and validated portable manufacturing documents.

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

9 endpoints in the toolpaths 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/toolpaths	toolpaths.list
post	/api/toolpaths	toolpaths.create
get	/api/toolpaths/{id}	toolpaths.get
put	/api/toolpaths/{id}	toolpaths.update
delete	/api/toolpaths/{id}	toolpaths.remove
get	/api/toolpaths/{id}/setup-sheet	toolpaths.setupSheet
post	/api/toolpaths/post-check	toolpaths.postCheck
get	/api/drawings/{id}/toolpaths	toolpaths.listForDrawing
post	/api/drawings/{id}/toolpaths	toolpaths.createForDrawing

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

One block per operation (9), 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/toolpaths

get /api/toolpaths # toolpaths.list

Requires Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
projectId	query	string \| null	optional
type	query	string \| null	optional
operationType	query	string \| null	optional
search	query	string \| null	optional
public	query	string \| null	optional

Responses

200 Array<object> application/json

Array<{
  id: string
  name: string
  description: string | null
  data: unknown
  type: string | null
  operationType: string | null
  gcode: string | null
  thumbnail: string | null
  isPublic: boolean
  projectId: string
  createdAt: string
  updatedAt: string
  createdBy: string
  drawingId: string | null
  materialId: string | null
  toolId: string | null
  machineConfigId: string | null
}>

401 UnauthorizedEncoded application/json

UnauthorizedEncoded

500 InternalErrorEncoded application/json

InternalErrorEncoded

Example response captured · 200

GET /api/toolpaths

[]

SDK example

toolpaths.list

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

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

// ToolpathsListInput
const result = await client.toolpaths.list({})

curl

GET /api/toolpaths

curl --request GET "${CADCAMFUN_URL}/api/toolpaths" \
  --header "Authorization: Bearer ${CADCAMFUN_TOKEN}"

Try it

projectId query type query operationType query search query public query

post /api/toolpaths # toolpaths.create

Requires Authorization: Bearer <token>.

Request body · required · application/json

{
  name?: string | null
  description?: string | null
  data?: unknown | null
  gcode?: string | null
  projectId?: string | null
  type?: string | null
  operationType?: string | null
  isPublic?: boolean | null
  thumbnail?: string | null
  materialId?: string | null
  machineConfigId?: string | null
  toolId?: string | null
  simulation?: unknown | null
  baseUpdatedAt?: string | null
}

Responses

201 object application/json

{
  id: string
  name: string
  description: string | null
  data: unknown
  type: string | null
  operationType: string | null
  gcode: string | null
  thumbnail: string | null
  isPublic: boolean
  projectId: string
  createdAt: string
  updatedAt: string
  createdBy: string
  drawingId: string | null
  materialId: string | null
  toolId: string | null
  machineConfigId: string | null
}

400 BadRequestEncoded application/json

BadRequestEncoded

401 UnauthorizedEncoded application/json

UnauthorizedEncoded

403 ForbiddenEncoded application/json

ForbiddenEncoded

404 NotFoundEncoded application/json

NotFoundEncoded

500 InternalErrorEncoded application/json

InternalErrorEncoded

SDK example

toolpaths.create

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

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

// ToolpathsCreateInput
const result = await client.toolpaths.create({
  name: "",
  description: "",
  data: null,
  gcode: "",
  projectId: "",
  type: "",
  operationType: "",
  isPublic: false,
  thumbnail: "",
  materialId: "",
  machineConfigId: "",
  toolId: "",
  simulation: null,
  baseUpdatedAt: ""
})

curl

POST /api/toolpaths

curl --request POST "${CADCAMFUN_URL}/api/toolpaths" \
  --header "Authorization: Bearer ${CADCAMFUN_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-binary @request.json

Try it

Request body application/json

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

Requires Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
id	path	string	required

Responses

200 object application/json

{
  id: string
  name: string
  description: string | null
  data: unknown
  type: string | null
  operationType: string | null
  gcode: string | null
  thumbnail: string | null
  isPublic: boolean
  projectId: string
  createdAt: string
  updatedAt: string
  createdBy: string
  drawingId: string | null
  materialId: string | null
  toolId: string | null
  machineConfigId: string | null
  project: {
    id: string
    name: string
    ownerId: string
  }
}

400 BadRequestEncoded application/json

BadRequestEncoded

401 UnauthorizedEncoded application/json

UnauthorizedEncoded

404 NotFoundEncoded application/json

NotFoundEncoded

500 InternalErrorEncoded application/json

InternalErrorEncoded

SDK example

toolpaths.get

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

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

// ToolpathsGetInput
const result = await client.toolpaths.get({
  id: "<id>"
})

curl

GET /api/toolpaths/{id}

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

Try it

id path · required

put /api/toolpaths/{id} # toolpaths.update

Requires Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
id	path	string	required

Request body · required · application/json

{
  name?: string | null
  description?: string | null
  data?: unknown | null
  gcode?: string | null
  projectId?: string | null
  type?: string | null
  operationType?: string | null
  isPublic?: boolean | null
  thumbnail?: string | null
  materialId?: string | null
  machineConfigId?: string | null
  toolId?: string | null
  simulation?: unknown | null
  baseUpdatedAt?: string | null
}

Responses

200 object application/json

{
  id: string
  name: string
  description: string | null
  data: unknown
  type: string | null
  operationType: string | null
  gcode: string | null
  thumbnail: string | null
  isPublic: boolean
  projectId: string
  createdAt: string
  updatedAt: string
  createdBy: string
  drawingId: string | null
  materialId: string | null
  toolId: string | null
  machineConfigId: string | null
  message: string
}

400 BadRequestEncoded application/json

BadRequestEncoded

401 UnauthorizedEncoded application/json

UnauthorizedEncoded

403 ForbiddenEncoded application/json

ForbiddenEncoded

404 NotFoundEncoded application/json

NotFoundEncoded

409 ConflictEncoded application/json

ConflictEncoded

500 InternalErrorEncoded application/json

InternalErrorEncoded

SDK example

toolpaths.update

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

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

// ToolpathsUpdateInput
const result = await client.toolpaths.update({
  id: "<id>",
  name: "",
  description: "",
  data: null,
  gcode: "",
  projectId: "",
  type: "",
  operationType: "",
  isPublic: false,
  thumbnail: "",
  materialId: "",
  machineConfigId: "",
  toolId: "",
  simulation: null,
  baseUpdatedAt: ""
})

curl

PUT /api/toolpaths/{id}

curl --request PUT "${CADCAMFUN_URL}/api/toolpaths/<id>" \
  --header "Authorization: Bearer ${CADCAMFUN_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-binary @request.json

Try it

id path · required

Request body application/json

delete /api/toolpaths/{id} # toolpaths.remove

Requires Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
id	path	string	required

Responses

200 object application/json

{
  message: string
}

400 BadRequestEncoded application/json

BadRequestEncoded

401 UnauthorizedEncoded application/json

UnauthorizedEncoded

403 ForbiddenEncoded application/json

ForbiddenEncoded

404 NotFoundEncoded application/json

NotFoundEncoded

500 InternalErrorEncoded application/json

InternalErrorEncoded

SDK example

toolpaths.remove

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

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

// ToolpathsRemoveInput
const result = await client.toolpaths.remove({
  id: "<id>"
})

curl

DELETE /api/toolpaths/{id}

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

Try it

id path · required

get /api/toolpaths/{id}/setup-sheet # toolpaths.setupSheet

Requires Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
id	path	string	required

Responses

200 object application/json

{
  data: {
    title: string
    jobId: string
    release: "blocked" | "preview" | "verified-program"
    material: {
      name: string
      iso: string
    }
    machine: {
      name: string
      post: string
    }
    setup: {
      orientation: string
      workOffset: string
      origin: {
        x: number
        y: number
        z: number
      }
      stock: {
        x: number
        y: number
        z: number
      }
    }
    tools: Array<{
      number: number
      id: string
      name: string
      kind: string
      diameter: number
      flutes: number
      fluteLength: number
      shankDiameter: number
      stickout: number
      holder?: string
      operations: string[]
      seconds: number
    }>
    operations: Array<{
      index: number
      id: string
      name: string
      strategy: string
      status: "ok" | "failed"
      tool?: number
      seconds: number
      cutLength: number
      removedVolume: number
      rpm?: number
      feed?: number
      ap?: number
      ae?: number
      warnings: string[]
    }>
    totals: {
      tools: number
      operations: number
      cycleSeconds: number
      cuttingSeconds: number
      removedVolume: number
    }
    claims: Array<{
      id: string
      status: string
      detail: string
    }>
    notes: string[]
    issues: Array<{
      severity: string
      message: string
    }>
    identity: {
      job: string
      part: string
      nc: string
      algorithm: string
    }
    titleBlock?: {
      [key: string]: string | number
    }
  }
  html: string
}

400 BadRequestEncoded application/json

BadRequestEncoded

401 UnauthorizedEncoded application/json

UnauthorizedEncoded

404 NotFoundEncoded application/json

NotFoundEncoded

500 InternalErrorEncoded application/json

InternalErrorEncoded

fetch example

toolpaths.setupSheet

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

curl

GET /api/toolpaths/{id}/setup-sheet

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

Try it

id path · required

/api/toolpaths/post-check

post /api/toolpaths/post-check # toolpaths.postCheck

Requires Authorization: Bearer <token>.

Request body · required · application/json

{
  definition: unknown
  sample?: boolean
}

Responses

200 object application/json

{
  valid: boolean
  issues: Array<{
    path: string
    message: string
  }>
  sample?: string
}

400 BadRequestEncoded application/json

BadRequestEncoded

401 UnauthorizedEncoded application/json

UnauthorizedEncoded

500 InternalErrorEncoded application/json

InternalErrorEncoded

fetch example

toolpaths.postCheck

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

curl

POST /api/toolpaths/post-check

curl --request POST "${CADCAMFUN_URL}/api/toolpaths/post-check" \
  --header "Authorization: Bearer ${CADCAMFUN_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-binary @request.json

Try it

Request body application/json

/api/drawings

get /api/drawings/{id}/toolpaths # toolpaths.listForDrawing

Requires Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
id	path	string	required

Responses

200 Array<object> application/json

Array<{
  id: string
  name: string
  description: string | null
  data: unknown
  type: string | null
  operationType: string | null
  gcode: string | null
  thumbnail: string | null
  isPublic: boolean
  projectId: string
  createdAt: string
  updatedAt: string
  createdBy: string
  drawingId: string | null
  materialId: string | null
  toolId: string | null
  machineConfigId: string | null
  Material: {
    id: string
    name: string
  } | null
  MachineConfig: {
    id: string
    name: string
    type: string
  } | null
  Tool: {
    id: string
    name: string
    type: string
    diameter: number | "Infinity" | "-Infinity" | "NaN"
  } | null
}>

400 BadRequestEncoded application/json

BadRequestEncoded

401 UnauthorizedEncoded application/json

UnauthorizedEncoded

404 NotFoundEncoded application/json

NotFoundEncoded

500 InternalErrorEncoded application/json

InternalErrorEncoded

SDK example

toolpaths.listForDrawing

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

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

// ToolpathsListForDrawingInput
const result = await client.toolpaths.listForDrawing({
  id: "<id>"
})

curl

GET /api/drawings/{id}/toolpaths

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

Try it

id path · required

post /api/drawings/{id}/toolpaths # toolpaths.createForDrawing

Requires Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
id	path	string	required

Request body · required · application/json

{
  name?: string | null
  description?: string | null
  data?: unknown | null
  gcode?: string | null
  projectId?: string | null
  type?: string | null
  operationType?: string | null
  isPublic?: boolean | null
  thumbnail?: string | null
  materialId?: string | null
  machineConfigId?: string | null
  toolId?: string | null
  simulation?: unknown | null
  baseUpdatedAt?: string | null
}

Responses

201 object application/json

{
  id: string
  name: string
  description: string | null
  data: unknown
  type: string | null
  operationType: string | null
  gcode: string | null
  thumbnail: string | null
  isPublic: boolean
  projectId: string
  createdAt: string
  updatedAt: string
  createdBy: string
  drawingId: string | null
  materialId: string | null
  toolId: string | null
  machineConfigId: string | null
}

400 BadRequestEncoded application/json

BadRequestEncoded

401 UnauthorizedEncoded application/json

UnauthorizedEncoded

403 ForbiddenEncoded application/json

ForbiddenEncoded

404 NotFoundEncoded application/json

NotFoundEncoded

500 InternalErrorEncoded application/json

InternalErrorEncoded

SDK example

toolpaths.createForDrawing

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

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

// ToolpathsCreateForDrawingInput
const result = await client.toolpaths.createForDrawing({
  id: "<id>",
  name: "",
  description: "",
  data: null,
  gcode: "",
  projectId: "",
  type: "",
  operationType: "",
  isPublic: false,
  thumbnail: "",
  materialId: "",
  machineConfigId: "",
  toolId: "",
  simulation: null,
  baseUpdatedAt: ""
})

curl

POST /api/drawings/{id}/toolpaths

curl --request POST "${CADCAMFUN_URL}/api/drawings/<id>/toolpaths" \
  --header "Authorization: Bearer ${CADCAMFUN_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-binary @request.json

Try it

id path · required

Request body application/json

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
}

ConflictEncoded

{
  _tag: "Conflict"
  message: string
}

ForbiddenEncoded

{
  _tag: "Forbidden"
  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 toolpaths.<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.