{
  "openapi": "3.1.1",
  "info": {
    "title": "Twinworks Line Capacity Calculator API",
    "version": "1.0.0",
    "summary": "Takt time, bottleneck, OEE, throughput and Little’s law lead time of a production line.",
    "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp."
  },
  "servers": [
    {
      "url": "https://twinworkslinecapacity.usefulweb.site"
    }
  ],
  "paths": {
    "/api/v1/calculate": {
      "post": {
        "operationId": "calculate",
        "summary": "Takt time, bottleneck, OEE, throughput and Little’s law lead time of a production line.",
        "description": "Analytic capacity of a serial production line: takt time from demand and available time, theoretical and effective capacity of every station with parallel machines and batch sizes, OEE = availability × performance × quality with downstream scrap, the bottleneck with and without losses, load at demand, Little’s law lead time for your work in process and the Factory Physics best-case, practical-worst-case and worst-case benchmarks. Enter stations or read them from a Twinworks model.\n\nMethodology:\n- Takt time = available time ÷ demand; demand rate = demand × 3600 ÷ available seconds.\n- Theoretical station capacity = parallel machines × units per cycle × 3600 ÷ cycle time (units/h). The slowest station is the theoretical bottleneck; its rate rb is the line’s theoretical throughput (the same rule as the Twinworks analytic check of a deterministic serial line).\n- OEE per station = availability × performance × quality (availability = run time ÷ planned time, performance = ideal cycle × units ÷ run time, quality = good ÷ processed). Effective processed rate = theoretical × A × P. Rejected units leave the line, so a station supports only (its processed rate × the product of its own and all downstream quality rates) good finished units per hour. The smallest of these is the effective throughput and the effective bottleneck.\n- Little’s law: WIP = throughput × lead time, so lead time = WIP ÷ effective throughput (long-run averages, any distributions).\n- Benchmarks for a given WIP w (Factory Physics): raw process time T0 = Σ cycle ÷ units per cycle, critical WIP W0 = rb × T0; best case TH = min(w ÷ T0, rb), practical worst case TH = rb × w ÷ (W0 + w − 1), worst case TH = 1 ÷ T0. A real line between best case and practical worst case is doing well; below practical worst case it has more variability than exponential.\n- From a Twinworks model: stations are the machine, assembly and quality nodes from the source to the sink in flow order; cycle = mean of the cycle distribution (or the ideal cycle time with performance = ideal ÷ mean), servers = parallel machines, availability = MTBF ÷ (MTBF + MTTR) with mean times, quality = 1 − scrap %.\n\nAnalytic averages for a steady line without starvation and blocking from variability; buffers, setups, shifts and random breakdowns can lower the real output — simulate the line in Twinworks to see those effects.",
        "tags": [
          "apps"
        ],
        "x-mcp-tool": "twinworks_line_capacity",
        "x-owner-app": "twinworks",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TwinworksLineCapacityInput"
              },
              "examples": {
                "example1": {
                  "summary": "Three stations, one with two parallel machines, OEE losses, 400 units per 450-minute shift",
                  "value": {
                    "stations": [
                      {
                        "name": "Saw",
                        "cycle": 40,
                        "availability": 95,
                        "performance": 95,
                        "quality": 99
                      },
                      {
                        "name": "Mill",
                        "cycle": 96,
                        "parallel": 2,
                        "availability": 85,
                        "performance": 90,
                        "quality": 98
                      },
                      {
                        "name": "Deburr",
                        "cycle": 38,
                        "availability": 98,
                        "performance": 95,
                        "quality": 100
                      }
                    ],
                    "availableMinutes": 450,
                    "demand": 400,
                    "wip": 20
                  }
                },
                "example2": {
                  "summary": "Twinworks template “Line with failures & shifts” read from the model, 100 units WIP",
                  "value": {
                    "template": "line-with-failures",
                    "availableMinutes": 900,
                    "demand": 1500,
                    "wip": 100
                  }
                },
                "example3": {
                  "summary": "Batch oven (24 parts per 30-minute cycle) between two cells",
                  "value": {
                    "stations": [
                      {
                        "name": "Press",
                        "cycle": 55,
                        "quality": 99.5
                      },
                      {
                        "name": "Oven",
                        "cycle": 1800,
                        "batch": 24,
                        "availability": 97
                      },
                      {
                        "name": "Pack",
                        "cycle": 45
                      }
                    ],
                    "availableMinutes": 960,
                    "demand": 900
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculation result envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TwinworksLineCapacityResult"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON body.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Invalid input (see errors[]).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (see Retry-After).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tool": {
      "get": {
        "operationId": "getToolDefinition",
        "summary": "Inputs, output schema and examples for this tool",
        "responses": {
          "200": {
            "description": "Tool definition.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Problem": {
        "type": "object",
        "description": "RFC 9457 problem details. 422 responses include per-field `errors`.",
        "required": [
          "type",
          "title",
          "status",
          "detail"
        ],
        "properties": {
          "type": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "field",
                "message"
              ],
              "properties": {
                "field": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "TwinworksLineCapacityInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "stations": {
            "title": "Stations in flow order",
            "description": "Cycle time per unit and machine (for a batch station: per batch). Availability, performance and quality in percent (empty = 100 %).",
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "name": {
                  "title": "Station",
                  "type": "string",
                  "maxLength": 60
                },
                "cycle": {
                  "title": "Cycle time (s)",
                  "type": "number",
                  "minimum": 0.001,
                  "maximum": 10000000
                },
                "parallel": {
                  "title": "Parallel machines",
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 1000
                },
                "batch": {
                  "title": "Units per cycle",
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 100000
                },
                "availability": {
                  "title": "Availability (%)",
                  "type": "number",
                  "minimum": 0.1,
                  "maximum": 100
                },
                "performance": {
                  "title": "Performance (%)",
                  "type": "number",
                  "minimum": 0.1,
                  "maximum": 100
                },
                "quality": {
                  "title": "Quality (%)",
                  "type": "number",
                  "minimum": 0.1,
                  "maximum": 100
                }
              },
              "required": [
                "name",
                "cycle"
              ]
            }
          },
          "template": {
            "title": "Or read the stations from a template",
            "type": "string",
            "enum": [
              "",
              "three-station-line",
              "line-with-failures",
              "assembly-two-feeders",
              "job-shop-routings",
              "bottleneck-buffer-sizing",
              "conveyor-packaging",
              "mm1-validation",
              "shared-forklifts"
            ],
            "default": ""
          },
          "model": {
            "title": "Or a Twinworks model JSON",
            "description": "A .twinworks.json project or model; the serial line from its source to its sink is read (mean cycle times, servers, MTBF/MTTR availability, ideal cycle time, scrap).",
            "type": "string",
            "maxLength": 400000
          },
          "availableMinutes": {
            "title": "Available time per period",
            "description": "Net production time, e.g. a 8 h shift minus 30 min breaks = 450 min.",
            "type": "number",
            "minimum": 0.01,
            "maximum": 1000000,
            "default": 450,
            "x-unit": "min"
          },
          "demand": {
            "title": "Demand per period",
            "description": "Optional: gives the takt time and the load at demand.",
            "type": "number",
            "minimum": 0.001,
            "maximum": 1000000000,
            "x-unit": "good units"
          },
          "wip": {
            "title": "Work in process",
            "description": "Optional: units in the line for Little’s law (lead time = WIP ÷ throughput).",
            "type": "number",
            "minimum": 0.001,
            "maximum": 1000000000,
            "x-unit": "units"
          }
        },
        "required": []
      },
      "TwinworksLineCapacityResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schemaVersion",
          "tool",
          "computedAt",
          "inputs",
          "summary",
          "result",
          "units",
          "assumptions",
          "sources",
          "warnings",
          "presentation",
          "links"
        ],
        "properties": {
          "schemaVersion": {
            "type": "string",
            "const": "1.0"
          },
          "tool": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "id",
              "name",
              "version"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "version": {
                "type": "string"
              }
            }
          },
          "computedAt": {
            "type": "string",
            "format": "date-time"
          },
          "inputs": {
            "type": "object",
            "description": "Normalised inputs actually used, including applied defaults."
          },
          "summary": {
            "type": "string"
          },
          "result": {
            "type": "object",
            "required": [
              "stations",
              "theoretical",
              "effective",
              "lineOee",
              "takt",
              "rawProcessTime",
              "criticalWip",
              "little",
              "warnings"
            ],
            "properties": {
              "stations": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "cycle": {
                      "type": "number"
                    },
                    "parallel": {
                      "type": "integer"
                    },
                    "batch": {
                      "type": "integer"
                    },
                    "availability": {
                      "type": "number"
                    },
                    "performance": {
                      "type": "number"
                    },
                    "quality": {
                      "type": "number"
                    },
                    "oee": {
                      "type": "number"
                    },
                    "theoreticalPerHour": {
                      "type": "number"
                    },
                    "effectivePerHour": {
                      "type": "number"
                    },
                    "downstreamYield": {
                      "type": "number"
                    },
                    "goodPerHour": {
                      "type": "number"
                    },
                    "effectiveCycle": {
                      "type": "number"
                    },
                    "utilization": {
                      "type": [
                        "number",
                        "null"
                      ]
                    }
                  }
                }
              },
              "theoretical": {
                "type": "object",
                "properties": {
                  "perHour": {
                    "type": "number"
                  },
                  "bottleneck": {
                    "type": "string"
                  },
                  "bottleneckIndex": {
                    "type": "integer"
                  },
                  "cycle": {
                    "type": "number"
                  }
                }
              },
              "effective": {
                "type": "object",
                "properties": {
                  "perHour": {
                    "type": "number"
                  },
                  "bottleneck": {
                    "type": "string"
                  },
                  "bottleneckIndex": {
                    "type": "integer"
                  },
                  "cycle": {
                    "type": "number"
                  }
                }
              },
              "lineOee": {
                "type": "number"
              },
              "takt": {
                "type": [
                  "object",
                  "null"
                ],
                "properties": {
                  "seconds": {
                    "type": "number"
                  },
                  "demandPerHour": {
                    "type": "number"
                  },
                  "meetsDemand": {
                    "type": "boolean"
                  },
                  "capacityGapPerHour": {
                    "type": "number"
                  },
                  "requiredOee": {
                    "type": "number"
                  }
                }
              },
              "rawProcessTime": {
                "type": "number"
              },
              "criticalWip": {
                "type": "number"
              },
              "little": {
                "type": [
                  "object",
                  "null"
                ]
              },
              "arrivalPerHour": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "warnings": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "units": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "assumptions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "title"
              ],
              "properties": {
                "title": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "publisher": {
                  "type": "string"
                },
                "retrievedAt": {
                  "type": "string"
                },
                "note": {
                  "type": "string"
                }
              }
            }
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "presentation": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Display blocks used by the human page (same data)."
          },
          "links": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "human",
              "api",
              "openapi",
              "methodology"
            ],
            "properties": {
              "human": {
                "type": "string",
                "format": "uri"
              },
              "api": {
                "type": "string",
                "format": "uri"
              },
              "openapi": {
                "type": "string",
                "format": "uri"
              },
              "methodology": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      }
    }
  }
}