{
  "openapi": "3.1.1",
  "info": {
    "title": "Storyboard Camera Move Planner API",
    "version": "1.0.0",
    "summary": "Plan a pan, tilt, push-in or roll and get the camera view for every frame.",
    "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://fliplinecameramove.usefulweb.app"
    }
  ],
  "paths": {
    "/api/v1/calculate": {
      "post": {
        "operationId": "calculate",
        "summary": "Plan a pan, tilt, push-in or roll and get the camera view for every frame.",
        "description": "Describe a 2-D camera move over a storyboard or animation canvas: start and end view centre, zoom and rotation, timing within the shot and a CSS easing. Get the view rectangle for every frame as a table and CSV, a plan drawing and an editable Story Desk board that plays the move in Flipline.\n\nMethodology:\n- Frames = round(seconds × FPS), at least 1. Frame 0 shows the start pose and the shot’s last frame the end pose; before the move’s start and after its end the camera holds. Easing uses the same CSS cubic-bezier engine as the Easing Curve tool and Motion Desk.\n- Centre and rotation interpolate linearly in eased progress. Zoom interpolates geometrically (equal ratios per frame), so a push-in keeps a steady apparent speed. Zoom 100% shows the whole canvas; the view is canvas size ÷ zoom.\n- View left/top/width/height are canvas pixels before rotation; the output is width × height and rotates the artwork by the negative camera roll around the view centre. A frame whose rotated view leaves the canvas shows paper there; such frames are counted.\n- The editable Story Desk board uses the same engine: its animatic preview, GIF and video exports draw the board through this camera. It is a 2-D crop-and-roll camera, not 3-D or parallax.",
        "tags": [
          "apps"
        ],
        "x-mcp-tool": "flipline_camera_move",
        "x-owner-app": "flipline",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FliplineCameraMoveInput"
              },
              "examples": {
                "example1": {
                  "summary": "Push in on a detail at 24 FPS",
                  "value": {}
                },
                "example2": {
                  "summary": "A slow pan left after a one-second hold",
                  "value": {
                    "preset": "pan-left",
                    "seconds": 4,
                    "easing": "ease-out",
                    "start": 25,
                    "end": 100
                  }
                },
                "example3": {
                  "summary": "A gentle roll while pulling out",
                  "value": {
                    "fromZoom": 180,
                    "toZoom": 110,
                    "fromRotation": -6,
                    "toRotation": 0,
                    "fromX": 46,
                    "toX": 50,
                    "toY": 50,
                    "seconds": 2.5,
                    "easing": "cubic-bezier(0.37, 0, 0.63, 1)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculation result envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FliplineCameraMoveResult"
                }
              }
            }
          },
          "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"
                }
              }
            }
          }
        }
      },
      "FliplineCameraMoveInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "width": {
            "title": "Canvas width (px)",
            "type": "integer",
            "minimum": 32,
            "maximum": 1600,
            "default": 960
          },
          "height": {
            "title": "Canvas height (px)",
            "type": "integer",
            "minimum": 32,
            "maximum": 1600,
            "default": 540
          },
          "fps": {
            "title": "Frame rate (FPS)",
            "type": "integer",
            "minimum": 1,
            "maximum": 30,
            "default": 24
          },
          "seconds": {
            "title": "Shot length (seconds)",
            "type": "number",
            "minimum": 0.05,
            "maximum": 120,
            "default": 3
          },
          "preset": {
            "title": "Camera preset",
            "type": "string",
            "enum": [
              "custom",
              "pan-left",
              "pan-right",
              "tilt-up",
              "tilt-down",
              "push-in",
              "pull-out",
              "handheld"
            ],
            "default": "custom"
          },
          "fromX": {
            "title": "Start centre X (%)",
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "default": 50
          },
          "fromY": {
            "title": "Start centre Y (%)",
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "default": 50
          },
          "fromZoom": {
            "title": "Start zoom (%)",
            "type": "number",
            "minimum": 100,
            "maximum": 800,
            "default": 100
          },
          "fromRotation": {
            "title": "Start rotation (degrees)",
            "type": "number",
            "minimum": -180,
            "maximum": 180,
            "default": 0
          },
          "toX": {
            "title": "End centre X (%)",
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "default": 58
          },
          "toY": {
            "title": "End centre Y (%)",
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "default": 45
          },
          "toZoom": {
            "title": "End zoom (%)",
            "type": "number",
            "minimum": 100,
            "maximum": 800,
            "default": 160
          },
          "toRotation": {
            "title": "End rotation (degrees)",
            "type": "number",
            "minimum": -180,
            "maximum": 180,
            "default": 0
          },
          "easing": {
            "title": "Easing (CSS timing function)",
            "type": "string",
            "maxLength": 200,
            "default": "ease-in-out"
          },
          "start": {
            "title": "Move starts at (% of shot)",
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "default": 0
          },
          "end": {
            "title": "Move ends at (% of shot)",
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "default": 100
          }
        },
        "required": []
      },
      "FliplineCameraMoveResult": {
        "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",
            "additionalProperties": false,
            "required": [
              "frames",
              "fps",
              "durationMs",
              "outsideFrames",
              "move",
              "table",
              "csv",
              "svg",
              "story",
              "openInApp"
            ],
            "properties": {
              "frames": {
                "type": "integer"
              },
              "fps": {
                "type": "integer"
              },
              "durationMs": {
                "type": "number"
              },
              "outsideFrames": {
                "type": "integer"
              },
              "move": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "from",
                  "to",
                  "start",
                  "end",
                  "ease"
                ],
                "description": "Animated camera over the board artwork. x/y: view centre as a fraction of the canvas; zoom 1 = whole canvas; start/end: fractions of the board duration; easing as in Motion Desk.",
                "properties": {
                  "from": {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "x",
                      "y",
                      "zoom",
                      "rotation"
                    ],
                    "properties": {
                      "x": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 1
                      },
                      "y": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 1
                      },
                      "zoom": {
                        "type": "number",
                        "minimum": 1,
                        "maximum": 8
                      },
                      "rotation": {
                        "type": "number",
                        "minimum": -180,
                        "maximum": 180
                      }
                    }
                  },
                  "to": {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "x",
                      "y",
                      "zoom",
                      "rotation"
                    ],
                    "properties": {
                      "x": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 1
                      },
                      "y": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 1
                      },
                      "zoom": {
                        "type": "number",
                        "minimum": 1,
                        "maximum": 8
                      },
                      "rotation": {
                        "type": "number",
                        "minimum": -180,
                        "maximum": 180
                      }
                    }
                  },
                  "start": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1
                  },
                  "end": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 1
                  },
                  "ease": {
                    "oneOf": [
                      {
                        "enum": [
                          "linear",
                          "ease",
                          "ease-in",
                          "ease-out",
                          "ease-in-out",
                          "hold"
                        ]
                      },
                      {
                        "type": "array",
                        "minItems": 4,
                        "maxItems": 4,
                        "items": {
                          "type": "number"
                        }
                      }
                    ]
                  }
                }
              },
              "table": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "frame",
                    "timeMs",
                    "x",
                    "y",
                    "zoom",
                    "rotation",
                    "cx",
                    "cy",
                    "width",
                    "height",
                    "left",
                    "top",
                    "inside"
                  ],
                  "properties": {
                    "frame": {
                      "type": "integer"
                    },
                    "timeMs": {
                      "type": "number"
                    },
                    "x": {
                      "type": "number"
                    },
                    "y": {
                      "type": "number"
                    },
                    "zoom": {
                      "type": "number"
                    },
                    "rotation": {
                      "type": "number"
                    },
                    "cx": {
                      "type": "number"
                    },
                    "cy": {
                      "type": "number"
                    },
                    "width": {
                      "type": "number"
                    },
                    "height": {
                      "type": "number"
                    },
                    "left": {
                      "type": "number"
                    },
                    "top": {
                      "type": "number"
                    },
                    "inside": {
                      "type": "boolean"
                    }
                  }
                }
              },
              "csv": {
                "type": "string"
              },
              "svg": {
                "type": "string"
              },
              "story": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "format",
                  "version",
                  "name",
                  "width",
                  "height",
                  "fps",
                  "paper",
                  "boards"
                ],
                "properties": {
                  "format": {
                    "const": "flipline-story"
                  },
                  "version": {
                    "enum": [
                      1,
                      2
                    ]
                  },
                  "name": {
                    "type": "string",
                    "maxLength": 120
                  },
                  "width": {
                    "type": "integer",
                    "minimum": 32,
                    "maximum": 1600
                  },
                  "height": {
                    "type": "integer",
                    "minimum": 32,
                    "maximum": 1600
                  },
                  "fps": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 30
                  },
                  "paper": {
                    "type": "string",
                    "pattern": "^#[a-fA-F0-9]{6}$"
                  },
                  "boards": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 48,
                    "items": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "id",
                        "title",
                        "scene",
                        "shot",
                        "camera",
                        "frames",
                        "action",
                        "dialogue",
                        "notes",
                        "locked",
                        "marks",
                        "reference"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "pattern": "^[-a-zA-Z0-9_]{1,80}$"
                        },
                        "title": {
                          "type": "string",
                          "maxLength": 80
                        },
                        "scene": {
                          "type": "string",
                          "maxLength": 80
                        },
                        "shot": {
                          "enum": [
                            "wide",
                            "medium",
                            "close",
                            "detail",
                            "over-shoulder"
                          ]
                        },
                        "camera": {
                          "enum": [
                            "static",
                            "pan-left",
                            "pan-right",
                            "tilt-up",
                            "tilt-down",
                            "push-in",
                            "pull-out",
                            "handheld"
                          ]
                        },
                        "frames": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 3600
                        },
                        "action": {
                          "type": "string",
                          "maxLength": 1200
                        },
                        "dialogue": {
                          "type": "string",
                          "maxLength": 1200
                        },
                        "notes": {
                          "type": "string",
                          "maxLength": 1200
                        },
                        "locked": {
                          "type": "boolean"
                        },
                        "marks": {
                          "type": "array",
                          "maxItems": 500,
                          "items": {
                            "type": "object",
                            "additionalProperties": false,
                            "required": [
                              "id",
                              "kind",
                              "points",
                              "color",
                              "size",
                              "fill"
                            ],
                            "properties": {
                              "brush": {
                                "type": "object",
                                "additionalProperties": false,
                                "required": [
                                  "kind",
                                  "opacity",
                                  "flow",
                                  "spacing",
                                  "texture",
                                  "pressure",
                                  "seed"
                                ],
                                "properties": {
                                  "kind": {
                                    "enum": [
                                      "ink",
                                      "pencil",
                                      "marker",
                                      "wash",
                                      "airbrush"
                                    ]
                                  },
                                  "opacity": {
                                    "type": "number",
                                    "minimum": 0,
                                    "maximum": 1
                                  },
                                  "flow": {
                                    "type": "number",
                                    "minimum": 0,
                                    "maximum": 1
                                  },
                                  "spacing": {
                                    "type": "number",
                                    "minimum": 0.08,
                                    "maximum": 1
                                  },
                                  "texture": {
                                    "type": "number",
                                    "minimum": 0,
                                    "maximum": 1
                                  },
                                  "pressure": {
                                    "type": "boolean"
                                  },
                                  "seed": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "maximum": 4294967295
                                  }
                                }
                              },
                              "pressures": {
                                "type": "array",
                                "minItems": 1,
                                "maxItems": 4096,
                                "items": {
                                  "type": "number",
                                  "minimum": 0,
                                  "maximum": 1
                                }
                              },
                              "id": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 80
                              },
                              "kind": {
                                "enum": [
                                  "pen",
                                  "eraser",
                                  "line",
                                  "rect",
                                  "ellipse",
                                  "image"
                                ]
                              },
                              "points": {
                                "type": "array",
                                "minItems": 1,
                                "maxItems": 4096,
                                "items": {
                                  "type": "array",
                                  "minItems": 2,
                                  "maxItems": 2,
                                  "items": {
                                    "type": "number",
                                    "minimum": 0,
                                    "maximum": 1
                                  }
                                }
                              },
                              "color": {
                                "type": "string",
                                "pattern": "^#[a-fA-F0-9]{6}$"
                              },
                              "size": {
                                "type": "number",
                                "minimum": 1,
                                "maximum": 100
                              },
                              "fill": {
                                "type": "boolean"
                              },
                              "source": {
                                "type": "string",
                                "pattern": "^data:image/(png|jpeg|webp);base64,[A-Za-z0-9+/=]+$"
                              },
                              "angle": {
                                "type": "number",
                                "minimum": -360,
                                "maximum": 360,
                                "description": "Clockwise rotation in degrees around the center of the mark bounds (normalized to -180…180)."
                              },
                              "flipX": {
                                "type": "boolean",
                                "description": "Mirror horizontally around the mark center."
                              },
                              "flipY": {
                                "type": "boolean",
                                "description": "Mirror vertically around the mark center."
                              }
                            }
                          }
                        },
                        "reference": {
                          "type": [
                            "object",
                            "null"
                          ],
                          "additionalProperties": false,
                          "required": [
                            "source",
                            "opacity",
                            "visible"
                          ],
                          "properties": {
                            "source": {
                              "type": "string",
                              "pattern": "^data:image/(png|jpeg|webp);base64,[A-Za-z0-9+/=]+$"
                            },
                            "opacity": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 1
                            },
                            "visible": {
                              "type": "boolean"
                            }
                          }
                        },
                        "move": {
                          "type": "object",
                          "additionalProperties": false,
                          "required": [
                            "from",
                            "to",
                            "start",
                            "end",
                            "ease"
                          ],
                          "description": "Animated camera over the board artwork. x/y: view centre as a fraction of the canvas; zoom 1 = whole canvas; start/end: fractions of the board duration; easing as in Motion Desk.",
                          "properties": {
                            "from": {
                              "type": "object",
                              "additionalProperties": false,
                              "required": [
                                "x",
                                "y",
                                "zoom",
                                "rotation"
                              ],
                              "properties": {
                                "x": {
                                  "type": "number",
                                  "minimum": 0,
                                  "maximum": 1
                                },
                                "y": {
                                  "type": "number",
                                  "minimum": 0,
                                  "maximum": 1
                                },
                                "zoom": {
                                  "type": "number",
                                  "minimum": 1,
                                  "maximum": 8
                                },
                                "rotation": {
                                  "type": "number",
                                  "minimum": -180,
                                  "maximum": 180
                                }
                              }
                            },
                            "to": {
                              "type": "object",
                              "additionalProperties": false,
                              "required": [
                                "x",
                                "y",
                                "zoom",
                                "rotation"
                              ],
                              "properties": {
                                "x": {
                                  "type": "number",
                                  "minimum": 0,
                                  "maximum": 1
                                },
                                "y": {
                                  "type": "number",
                                  "minimum": 0,
                                  "maximum": 1
                                },
                                "zoom": {
                                  "type": "number",
                                  "minimum": 1,
                                  "maximum": 8
                                },
                                "rotation": {
                                  "type": "number",
                                  "minimum": -180,
                                  "maximum": 180
                                }
                              }
                            },
                            "start": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 1
                            },
                            "end": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 1
                            },
                            "ease": {
                              "oneOf": [
                                {
                                  "enum": [
                                    "linear",
                                    "ease",
                                    "ease-in",
                                    "ease-out",
                                    "ease-in-out",
                                    "hold"
                                  ]
                                },
                                {
                                  "type": "array",
                                  "minItems": 4,
                                  "maxItems": 4,
                                  "items": {
                                    "type": "number"
                                  }
                                }
                              ]
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "description": "Story Desk. Frame-based board durations, half-open timeline intervals and non-drop-frame timecodes. Up to 600 seconds total and 120 seconds per board at the chosen FPS. Canvas up to 2 MP, 50000 points, 2000 marks and 6 million source-image characters across all boards. Ink erasers affect preceding ink only; the independent reference is preserved. The camera field is a planning label; an optional move animates a 2-D camera (pan, tilt, zoom, roll) over the board artwork in previews and animatic exports, and requires version 2."
              },
              "openInApp": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "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"
              }
            }
          }
        }
      }
    }
  }
}