{
  "openapi": "3.1.1",
  "info": {
    "title": "Trackwell Jira CSV Import API",
    "version": "1.0.0",
    "summary": "Turn a Jira CSV export into a Trackwell project: issues, statuses, sprints, people.",
    "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://trackwelljiracsvimport.usefulweb.app"
    }
  ],
  "paths": {
    "/api/v1/calculate": {
      "post": {
        "operationId": "calculate",
        "summary": "Turn a Jira CSV export into a Trackwell project: issues, statuses, sprints, people.",
        "description": "Reads the CSV file Jira exports for a filter (all fields) and maps it to a Trackwell project file: issue types, statuses with their category, priorities, assignees and reporters, labels, components, fix versions, sprints, story points, estimates, time spent, parents, links, comments and custom fields. It reports exactly what was mapped and what was left out.\n\nMethodology:\n- Columns are found by their Jira header names; repeated columns (Labels, Component/s, Fix Version/s, Sprint, Comment, Watchers) are all read. Trackwell’s own CSV export uses the same names, so it reads back the same way.\n- Issue types: Bug, Story, Epic, Sub-task, Incident (also Problem) and requests (Service request, IT help, Access, Support, Question) map to Trackwell types; everything else becomes Task. Priorities: Blocker/Critical → Highest, Major → High, Minor → Low, Trivial → Lowest.\n- Each distinct status becomes a workflow status; its category comes from the “Status Category” column, else from the name (Done/Closed/Resolved → done; In Progress/Review/Testing/Waiting → in progress). The imported workflow allows every move; refine it in the workflow editor.\n- Sprints: an issue’s last Sprint column is its current sprint; sprints that were followed by another one are closed, the open sprint with the most open issues becomes active. Story points come from “Custom field (Story Points)” or “(Story point estimate)”; Original Estimate and Time Spent are seconds in Jira and become minutes. Other “Custom field (…)” columns become text or number fields.\n- Dates in Jira’s default format (24/Nov/26 9:15 AM) or ISO are read as UTC. Parents are found by “Parent id”/“Parent” (Jira issue id or key); “Inward/Outward issue link (…)” columns become links between imported issues. Comments keep author and time; Jira wiki markup (h2., *bold*, {code}) becomes Markdown.\n\nJira is a trademark of Atlassian. Trackwell reads the export file you provide; it does not connect to Jira. Attachments, work log details and change history are not part of Jira’s CSV export.",
        "tags": [
          "apps"
        ],
        "x-mcp-tool": "trackwell_jira_csv_import",
        "x-owner-app": "trackwell",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TrackwellJiraCsvImportInput"
              },
              "examples": {
                "example1": {
                  "summary": "Small mobile app project (epic, stories, bugs, sub-task, two sprints)",
                  "value": {
                    "csv": "Summary,Issue key,Issue id,Issue Type,Status,Status Category,Project key,Project name,Priority,Resolution,Assignee,Reporter,Created,Updated,Resolved,Due Date,Labels,Labels,Component/s,Fix Version/s,Sprint,Sprint,Custom field (Story Points),Original Estimate,Time Spent,Parent id,Description,Comment,Comment,Outward issue link (Blocks),Custom field (Customer)\nMobile app onboarding,APP-1,10001,Epic,In Progress,In Progress,APP,Mobile app,High,,Priya Shah,Tom Becker,02/Nov/26 9:00 AM,20/Nov/26 4:10 PM,,,onboarding,,iOS,1.4,,,,,,,\"Everything a new user sees in the first five minutes.\",,,,\nWelcome screens with skip button,APP-2,10002,Story,Done,Done,APP,Mobile app,Medium,Done,Priya Shah,Tom Becker,02/Nov/26 9:30 AM,12/Nov/26 3:00 PM,12/Nov/26 3:00 PM,,onboarding,ux,iOS,1.4,APP Sprint 7,APP Sprint 8,5,28800,25200,10001,\"h2. Goal\n*Three* screens and a skip button.\n* Screen 1: value\n* Screen 2: privacy\n* Screen 3: start\",\"05/Nov/26 10:12 AM;Tom Becker;Looks good on the small phones too.\",,,\nPush permission prompt at the right moment,APP-3,10003,Story,In Progress,In Progress,APP,Mobile app,Medium,,Luis Ortega,Tom Becker,03/Nov/26 11:00 AM,21/Nov/26 9:20 AM,,28/Nov/26,onboarding,,iOS,1.4,APP Sprint 8,,3,14400,7200,10001,Ask only after the first saved item.,\"18/Nov/26 2:05 PM;Luis Ortega;Blocked until APP-5 is merged.\",,,\nCrash when the camera permission is denied,APP-4,10004,Bug,To Do,To Do,APP,Mobile app,Highest,,,Anna Kowalski,19/Nov/26 8:45 AM,19/Nov/26 8:45 AM,,,crash,,Android,1.4,APP Sprint 8,,,,,,\"{code}java.lang.SecurityException: camera{code}\",,,,ACME\nAnalytics event for skipped onboarding,APP-5,10005,Task,In Review,In Progress,APP,Mobile app,Low,,Priya Shah,Priya Shah,10/Nov/26 1:00 PM,20/Nov/26 5:30 PM,,,analytics,,,,APP Sprint 8,,2,7200,5400,10001,,,,APP-3,\nOld splash screen still shown on tablets,APP-6,10006,Bug,Done,Done,APP,Mobile app,Medium,Won't Do,Luis Ortega,Anna Kowalski,25/Oct/26 3:00 PM,04/Nov/26 10:00 AM,04/Nov/26 10:00 AM,,tablet,,Android,,APP Sprint 7,,1,,,,Tablets use the new layout from 1.4.,,,,\nTranslate onboarding into Spanish,APP-7,10007,Sub-task,To Do,To Do,APP,Mobile app,Medium,,,Tom Becker,20/Nov/26 9:00 AM,20/Nov/26 9:00 AM,,05/Dec/26,i18n,,iOS,1.4,,,,3600,,10002,,,,,\nReset password link expired too early,APP-8,10008,Bug,Waiting for customer,In Progress,APP,Mobile app,High,,Anna Kowalski,Customer Care,17/Nov/26 4:20 PM,18/Nov/26 9:00 AM,,,auth,,Android,,,,,,1800,,Customer says the link expired after 5 minutes.,,,,Globex"
                  }
                },
                "example2": {
                  "summary": "Same file as a kanban project with another key",
                  "value": {
                    "csv": "Summary,Issue key,Issue id,Issue Type,Status,Status Category,Project key,Project name,Priority,Resolution,Assignee,Reporter,Created,Updated,Resolved,Due Date,Labels,Labels,Component/s,Fix Version/s,Sprint,Sprint,Custom field (Story Points),Original Estimate,Time Spent,Parent id,Description,Comment,Comment,Outward issue link (Blocks),Custom field (Customer)\nMobile app onboarding,APP-1,10001,Epic,In Progress,In Progress,APP,Mobile app,High,,Priya Shah,Tom Becker,02/Nov/26 9:00 AM,20/Nov/26 4:10 PM,,,onboarding,,iOS,1.4,,,,,,,\"Everything a new user sees in the first five minutes.\",,,,\nWelcome screens with skip button,APP-2,10002,Story,Done,Done,APP,Mobile app,Medium,Done,Priya Shah,Tom Becker,02/Nov/26 9:30 AM,12/Nov/26 3:00 PM,12/Nov/26 3:00 PM,,onboarding,ux,iOS,1.4,APP Sprint 7,APP Sprint 8,5,28800,25200,10001,\"h2. Goal\n*Three* screens and a skip button.\n* Screen 1: value\n* Screen 2: privacy\n* Screen 3: start\",\"05/Nov/26 10:12 AM;Tom Becker;Looks good on the small phones too.\",,,\nPush permission prompt at the right moment,APP-3,10003,Story,In Progress,In Progress,APP,Mobile app,Medium,,Luis Ortega,Tom Becker,03/Nov/26 11:00 AM,21/Nov/26 9:20 AM,,28/Nov/26,onboarding,,iOS,1.4,APP Sprint 8,,3,14400,7200,10001,Ask only after the first saved item.,\"18/Nov/26 2:05 PM;Luis Ortega;Blocked until APP-5 is merged.\",,,\nCrash when the camera permission is denied,APP-4,10004,Bug,To Do,To Do,APP,Mobile app,Highest,,,Anna Kowalski,19/Nov/26 8:45 AM,19/Nov/26 8:45 AM,,,crash,,Android,1.4,APP Sprint 8,,,,,,\"{code}java.lang.SecurityException: camera{code}\",,,,ACME\nAnalytics event for skipped onboarding,APP-5,10005,Task,In Review,In Progress,APP,Mobile app,Low,,Priya Shah,Priya Shah,10/Nov/26 1:00 PM,20/Nov/26 5:30 PM,,,analytics,,,,APP Sprint 8,,2,7200,5400,10001,,,,APP-3,\nOld splash screen still shown on tablets,APP-6,10006,Bug,Done,Done,APP,Mobile app,Medium,Won't Do,Luis Ortega,Anna Kowalski,25/Oct/26 3:00 PM,04/Nov/26 10:00 AM,04/Nov/26 10:00 AM,,tablet,,Android,,APP Sprint 7,,1,,,,Tablets use the new layout from 1.4.,,,,\nTranslate onboarding into Spanish,APP-7,10007,Sub-task,To Do,To Do,APP,Mobile app,Medium,,,Tom Becker,20/Nov/26 9:00 AM,20/Nov/26 9:00 AM,,05/Dec/26,i18n,,iOS,1.4,,,,3600,,10002,,,,,\nReset password link expired too early,APP-8,10008,Bug,Waiting for customer,In Progress,APP,Mobile app,High,,Anna Kowalski,Customer Care,17/Nov/26 4:20 PM,18/Nov/26 9:00 AM,,,auth,,Android,,,,,,1800,,Customer says the link expired after 5 minutes.,,,,Globex",
                    "key": "MOB",
                    "name": "Mobile onboarding",
                    "mode": "kanban"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculation result envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrackwellJiraCsvImportResult"
                }
              }
            }
          },
          "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"
                }
              }
            }
          }
        }
      },
      "TrackwellJiraCsvImportInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "csv": {
            "title": "Jira CSV export",
            "description": "In Jira: Filters → search → Export → Export Excel CSV (all fields). Paste it here or upload the file.",
            "type": "string",
            "maxLength": 5000000,
            "default": ""
          },
          "csvFile": {
            "title": "CSV file (optional)",
            "description": "Used instead of the pasted text when given. Upload as {filename, contentType?, contentBase64}. Max 19531 KiB. Accepts .csv,text/csv.",
            "type": "object",
            "additionalProperties": false,
            "required": [
              "filename",
              "contentBase64"
            ],
            "properties": {
              "filename": {
                "type": "string"
              },
              "contentType": {
                "type": "string"
              },
              "contentBase64": {
                "type": "string"
              }
            }
          },
          "key": {
            "title": "Project key (optional)",
            "description": "Empty = taken from the issue keys.",
            "type": "string",
            "maxLength": 10,
            "default": ""
          },
          "name": {
            "title": "Project name (optional)",
            "type": "string",
            "maxLength": 120,
            "default": ""
          },
          "mode": {
            "title": "Board",
            "type": "string",
            "enum": [
              "auto",
              "scrum",
              "kanban"
            ],
            "default": "auto"
          }
        },
        "required": []
      },
      "TrackwellJiraCsvImportResult": {
        "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": [
              "counts",
              "statuses",
              "types"
            ],
            "properties": {
              "counts": {
                "type": "object"
              },
              "statuses": {
                "type": "array"
              },
              "types": {
                "type": "array"
              },
              "columns": {
                "type": "array"
              },
              "warnings": {
                "type": "array"
              },
              "key": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "projectArtifact": {
                "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"
              }
            }
          }
        }
      }
    }
  }
}