Skip to content

FiberPath API Reference

The FastAPI service in fiberpath_api/ exposes thin wrappers around the core planning, simulation, validation, and plotting engines. All endpoints are body-only: requests carry the data itself (a wind definition or a G-code program), never filesystem paths. This keeps the service stateless and safe to run as a local sidecar. Use FastAPI's autogenerated docs at /docs for interactive exploration.

Compute results (/plan, /simulate) share one versioned wire schema defined in fiberpath/wire.py: fields are camelCase and every response carries a schemaVersion. The wire format is deliberately decoupled from the internal engine dataclasses.

Planning

POST /plan

Request body: a wind definition (the same JSON as a .wind file).

{
  "layers": [{ "windType": "hoop", "terminal": false }],
  "mandrelParameters": { "diameter": 70.0, "windLength": 500.0 },
  "towParameters": { "width": 7.0, "thickness": 0.5 },
  "defaultFeedRate": 9000.0
}

See the Axis Mapping Guide for format details. Output is always XAB G-code.

Response body:

{
  "schemaVersion": "1.0",
  "commandCount": 1234,
  "gcode": "; Parameters {...}\nG0 X0 A0 B0\n...",
  "timeSeconds": 42.5,
  "towMeters": 8.1,
  "layers": [
    {
      "index": 1,
      "windType": "helical",
      "commandCount": 456,
      "timeSeconds": 12.3,
      "cumulativeTimeSeconds": 12.3,
      "towMeters": 1.9,
      "cumulativeTowMeters": 1.9,
      "terminal": false
    }
  ]
}

The generated program is returned in gcode; feed it directly to /simulate or /plot.

Simulation

POST /simulate

Request: a G-code program.

{ "gcode": "; Parameters ...\nG0 F6000\nG0 X10\n" }

Response:

{
  "schemaVersion": "1.0",
  "commandsExecuted": 789,
  "moves": 300,
  "estimatedTimeSeconds": 95.2,
  "totalDistanceMm": 8234.5,
  "towLengthMm": 8100.0,
  "averageFeedRateMmpm": 7200.0
}

Response Fields:

  • commandsExecuted: Total G-code commands processed
  • moves: Number of movement commands (G0/G1)
  • estimatedTimeSeconds: Estimated execution time in seconds
  • totalDistanceMm: Combined motion distance of all axes
  • towLengthMm: Total fiber material used in millimeters
  • averageFeedRateMmpm: Mean speed across all moves in mm/min

Validation

POST /validate

Validates a wind definition (schema and semantic layer bounds) without returning G-code.

Request: a wind definition body (as for /plan).

Response (success):

{ "valid": true }

On failure the service returns a non-2xx status with a {"detail": "..."} payload:

  • 200 OK: definition is valid
  • 400 Bad Request: semantic validation failed (e.g. out-of-range wind angle)
  • 422 Unprocessable Entity: the body is structurally malformed

Plot / preview

POST /plot

Renders an unwrapped 2D preview of a G-code program.

Request: a G-code program.

{ "gcode": "; Parameters ...\nG0 X10 A360\n" }

Response: image/png bytes (the rendered preview).

Machine streaming

The serial/streaming surface has been removed from the compute API. Driving a Marlin controller is being reworked into a dedicated REST surface (ports, connection, synchronous commands, and a polled /jobs resource) — see issues #190 and #199.

All endpoints return non-2xx responses (400/422) with a {"detail": "..."} payload when validation fails or the underlying engine reports an error.