{
  "openapi": "3.0.1",
  "info": {
    "title": "Fluid Portfolio Health MCP API",
    "version": "1.2.0",
    "description": "Portfolio health endpoints for project discovery, health scoring, governance reporting, and portfolio manager aggregates (top projects, low governance, executive summary)."
  },
  "servers": [
    {
      "url": "https://{tenant}.fluid.work",
      "description": "Your Fluid tenant. Replace {tenant} with your organisation's subdomain.",
      "variables": {
        "tenant": {
          "default": "your-tenant",
          "description": "Fluid tenant subdomain, e.g. 'acme' for https://acme.fluid.work. Sandbox tenants use '{tenant}-sandbox'."
        }
      }
    }
  ],
  "security": [
    {
      "basicAuth": []
    }
  ],
  "tags": [
    {
      "name": "Portfolio Health",
      "description": "Portfolio-level search and governance health reporting tools."
    }
  ],
  "paths": {
    "/rest/api/portfolio-manager/projects": {
      "get": {
        "tags": [
          "Portfolio Health"
        ],
        "summary": "List portfolio projects",
        "description": "Returns projects in the selected portfolio scope with RAG status and governance score for each project.",
        "operationId": "get-portfolio-projects",
        "parameters": [
          {
            "name": "guid",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Optional portfolio/programme/project scope GUID; omit for all projects visible to the caller."
          },
          {
            "name": "includeChildren",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": true
            },
            "description": "Include child projects of the scope."
          },
          {
            "name": "reportable",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Restrict to reportable (promoted) projects."
          }
        ],
        "responses": {
          "200": {
            "description": "Portfolio project list.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PortfolioProjectListResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "basicAuth": []
          }
        ]
      }
    },
    "/rest/api/portfolio-manager/projects/top": {
      "get": {
        "tags": [
          "Portfolio Health"
        ],
        "summary": "Get top projects by criteria",
        "description": "Ranks projects in scope by portfolio manager criteria. criteria=risk ranks by open high-severity impacts, then RAG severity, then governance score; criteria=health or governance ranks by governance score first.",
        "operationId": "get-top-projects",
        "parameters": [
          {
            "name": "top",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 10
            },
            "description": "Number of projects to return."
          },
          {
            "name": "criteria",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "risk",
                "health",
                "governance"
              ],
              "default": "risk"
            },
            "description": "Ranking criteria."
          },
          {
            "name": "guid",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Optional portfolio/programme/project scope GUID; omit for all projects visible to the caller."
          },
          {
            "name": "includeChildren",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": true
            },
            "description": "Include child projects of the scope."
          },
          {
            "name": "reportable",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Restrict to reportable (promoted) projects."
          }
        ],
        "responses": {
          "200": {
            "description": "Top projects by criteria.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PortfolioTopProjectsResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "basicAuth": []
          }
        ]
      }
    },
    "/rest/api/portfolio-manager/projects/low-governance": {
      "get": {
        "tags": [
          "Portfolio Health"
        ],
        "summary": "Get low-governance projects",
        "description": "Returns projects in scope whose governance result is below Good, worst first. Borderline projects can be included or excluded.",
        "operationId": "get-low-governance",
        "parameters": [
          {
            "name": "top",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            },
            "description": "Maximum number of projects to return."
          },
          {
            "name": "includeBorderline",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": true
            },
            "description": "Include projects with a Borderline governance result."
          },
          {
            "name": "guid",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Optional portfolio/programme/project scope GUID; omit for all projects visible to the caller."
          },
          {
            "name": "includeChildren",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": true
            },
            "description": "Include child projects of the scope."
          },
          {
            "name": "reportable",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Restrict to reportable (promoted) projects."
          }
        ],
        "responses": {
          "200": {
            "description": "Low-governance projects.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PortfolioLowGovernanceResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "basicAuth": []
          }
        ]
      }
    },
    "/rest/api/portfolio-manager/executive-summary": {
      "get": {
        "tags": [
          "Portfolio Health"
        ],
        "summary": "Get portfolio executive summary",
        "description": "Returns an aggregate executive summary for the scope: RAG health distribution, key upcoming milestones, and key open impacts/risks/issues.",
        "operationId": "get-exec-summary",
        "parameters": [
          {
            "name": "milestoneCount",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 10
            },
            "description": "Number of key milestones to include."
          },
          {
            "name": "impactCount",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 10
            },
            "description": "Number of key impacts to include."
          },
          {
            "name": "includeCompletedMilestones",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Include completed/cancelled/closed milestones."
          },
          {
            "name": "guid",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Optional portfolio/programme/project scope GUID; omit for all projects visible to the caller."
          },
          {
            "name": "includeChildren",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": true
            },
            "description": "Include child projects of the scope."
          },
          {
            "name": "reportable",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Restrict to reportable (promoted) projects."
          }
        ],
        "responses": {
          "200": {
            "description": "Executive summary aggregate dataset.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PortfolioExecutiveSummaryResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "basicAuth": []
          }
        ]
      }
    },
    "/rest/api/project/find": {
      "get": {
        "tags": [
          "Portfolio Health"
        ],
        "summary": "Find projects by keyword",
        "description": "Finds projects by matching title, description, epic, or theme using case-insensitive keyword search.",
        "operationId": "find-projects-get",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Keyword text to search."
          },
          {
            "name": "version",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Optional API version selector."
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated list of project fields to return."
          },
          {
            "name": "expand",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated expand options."
          },
          {
            "name": "skip",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "take",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching projects.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ObjectListResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "basicAuth": []
          }
        ]
      },
      "post": {
        "tags": [
          "Portfolio Health"
        ],
        "summary": "Find projects with request model",
        "description": "Finds projects using a request body query string. Supports the same paging and projection options as the GET route.",
        "operationId": "find-projects-pst",
        "parameters": [
          {
            "name": "version",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "expand",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "skip",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "take",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 50
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FindProjectsRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Matching projects.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ObjectListResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "basicAuth": []
          }
        ]
      }
    },
    "/api/v3/metrics/GetGroupResultCounts": {
      "get": {
        "tags": [
          "Portfolio Health"
        ],
        "summary": "Get grouped metric counts",
        "description": "Returns grouped pass, at-risk, and failed counts across governance assessment groups.",
        "operationId": "get-metric-grp-result-counts",
        "parameters": [
          {
            "name": "includeChildren",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Metric group counts.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetricGroupedCountResult"
                }
              }
            }
          }
        },
        "security": [
          {
            "basicAuth": []
          }
        ]
      }
    },
    "/api/v3/metrics/GetGroupResults": {
      "get": {
        "tags": [
          "Portfolio Health"
        ],
        "summary": "Get grouped metric results",
        "description": "Returns aggregate governance scoring across configured metric groups.",
        "operationId": "get-metric-grp-results",
        "parameters": [
          {
            "name": "includeChildren",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Metric grouped result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetricGroupedResult"
                }
              }
            }
          }
        },
        "security": [
          {
            "basicAuth": []
          }
        ]
      }
    },
    "/rest/api/project/summary": {
      "get": {
        "tags": [
          "Portfolio Health"
        ],
        "summary": "Get project summary",
        "description": "Returns portfolio summary data including project RAG status and custom property metadata.",
        "operationId": "get-project-summ",
        "parameters": [
          {
            "name": "showChildren",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "reportable",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "guid",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "Both",
                "Activity",
                "Children"
              ],
              "default": "Both"
            }
          },
          {
            "name": "showProjectRoles",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": true
            }
          },
          {
            "name": "getExtendedHierarchy",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Project summary response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectSummaryApiResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "basicAuth": []
          }
        ]
      }
    },
    "/api/v3/project/search": {
      "post": {
        "tags": [
          "Portfolio Health"
        ],
        "summary": "Search projects with filters",
        "description": "Searches projects using filterQuery, showChildren, and expand options for portfolio slicing and reporting.",
        "operationId": "search-projects",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProjectSearchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Matching projects.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ObjectListResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "basicAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic",
        "description": "Use your Fluid PAT or Base64 PAT token."
      }
    },
    "schemas": {
      "FindProjectsRequest": {
        "type": "object",
        "required": [
          "query"
        ],
        "properties": {
          "query": {
            "type": "string",
            "description": "Keyword used to find projects."
          }
        }
      },
      "ProjectSearchRequest": {
        "type": "object",
        "properties": {
          "filterQuery": {
            "type": "string",
            "description": "ProjectQueryManager filter expression."
          },
          "showChildren": {
            "type": "boolean",
            "description": "Include child projects in the result."
          },
          "expand": {
            "type": "string",
            "description": "Expansion mode, for example compact."
          }
        }
      },
      "MetricGroupedResult": {
        "type": "object",
        "properties": {
          "asOfDate": {
            "type": "string",
            "format": "date-time"
          },
          "score": {
            "type": "number"
          },
          "passScore": {
            "type": "number"
          },
          "count": {
            "type": "integer"
          },
          "goodCount": {
            "type": "integer"
          },
          "needsImprovementCount": {
            "type": "integer"
          },
          "atRiskCount": {
            "type": "integer"
          },
          "group1Score": {
            "type": "number"
          },
          "group2Score": {
            "type": "number"
          },
          "group3Score": {
            "type": "number"
          },
          "group4Score": {
            "type": "number"
          },
          "group5Score": {
            "type": "number"
          },
          "group6Score": {
            "type": "number"
          }
        }
      },
      "MetricGroupedCountResult": {
        "type": "object",
        "properties": {
          "count": {
            "type": "integer"
          },
          "good": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          },
          "atRisk": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          },
          "failed": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          }
        }
      },
      "ProjectSummaryApiResponse": {
        "type": "object",
        "properties": {
          "projects": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "customPropertyMetadata": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        }
      },
      "ObjectListResponse": {
        "type": "array",
        "items": {
          "type": "object",
          "additionalProperties": true
        }
      },
      "PortfolioProjectListResponse": {
        "type": "object",
        "properties": {
          "scopeGuid": {
            "type": "string"
          },
          "includeChildren": {
            "type": "boolean"
          },
          "totalCount": {
            "type": "integer"
          },
          "projects": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PortfolioProjectListItem"
            }
          }
        }
      },
      "PortfolioProjectListItem": {
        "type": "object",
        "properties": {
          "projectGuid": {
            "type": "string"
          },
          "projectName": {
            "type": "string"
          },
          "portfolio": {
            "type": "string"
          },
          "subPortfolio": {
            "type": "string"
          },
          "parentGuid": {
            "type": "string"
          },
          "parentName": {
            "type": "string"
          },
          "programGuid": {
            "type": "string"
          },
          "programName": {
            "type": "string"
          },
          "ragStatus": {
            "type": "string"
          },
          "ragOrder": {
            "type": "integer"
          },
          "governanceScore": {
            "type": "number"
          },
          "governancePassScore": {
            "type": "number"
          },
          "governanceResult": {
            "type": "string"
          }
        }
      },
      "PortfolioTopProjectsResponse": {
        "type": "object",
        "properties": {
          "scopeGuid": {
            "type": "string"
          },
          "includeChildren": {
            "type": "boolean"
          },
          "criteria": {
            "type": "string"
          },
          "requestedTop": {
            "type": "integer"
          },
          "totalProjects": {
            "type": "integer"
          },
          "projects": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PortfolioTopProjectItem"
            }
          }
        }
      },
      "PortfolioTopProjectItem": {
        "type": "object",
        "properties": {
          "projectGuid": {
            "type": "string"
          },
          "projectName": {
            "type": "string"
          },
          "portfolio": {
            "type": "string"
          },
          "ragStatus": {
            "type": "string"
          },
          "ragOrder": {
            "type": "integer"
          },
          "governanceScore": {
            "type": "number"
          },
          "governancePassScore": {
            "type": "number"
          },
          "governanceResult": {
            "type": "string"
          },
          "openImpactCount": {
            "type": "integer"
          },
          "openRiskCount": {
            "type": "integer"
          },
          "openIssueCount": {
            "type": "integer"
          },
          "openHighSeverityCount": {
            "type": "integer"
          }
        }
      },
      "PortfolioLowGovernanceResponse": {
        "type": "object",
        "properties": {
          "scopeGuid": {
            "type": "string"
          },
          "includeChildren": {
            "type": "boolean"
          },
          "includeBorderline": {
            "type": "boolean"
          },
          "requestedTop": {
            "type": "integer"
          },
          "totalProjects": {
            "type": "integer"
          },
          "projects": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PortfolioLowGovernanceProject"
            }
          }
        }
      },
      "PortfolioLowGovernanceProject": {
        "type": "object",
        "properties": {
          "projectGuid": {
            "type": "string"
          },
          "projectName": {
            "type": "string"
          },
          "portfolio": {
            "type": "string"
          },
          "ragStatus": {
            "type": "string"
          },
          "governanceScore": {
            "type": "number"
          },
          "governancePassScore": {
            "type": "number"
          },
          "governanceResult": {
            "type": "string"
          },
          "failedGroups": {
            "type": "integer"
          },
          "borderlineGroups": {
            "type": "integer"
          }
        }
      },
      "PortfolioExecutiveSummaryResponse": {
        "type": "object",
        "properties": {
          "scopeGuid": {
            "type": "string"
          },
          "includeChildren": {
            "type": "boolean"
          },
          "projectCount": {
            "type": "integer"
          },
          "lowGovernanceProjectCount": {
            "type": "integer"
          },
          "statusHealth": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PortfolioStatusHealthItem"
            }
          },
          "keyMilestones": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PortfolioMilestoneSummaryItem"
            }
          },
          "impactSummary": {
            "$ref": "#/components/schemas/PortfolioImpactAggregate"
          }
        }
      },
      "PortfolioStatusHealthItem": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "count": {
            "type": "integer"
          }
        }
      },
      "PortfolioMilestoneSummaryItem": {
        "type": "object",
        "properties": {
          "milestoneGuid": {
            "type": "string"
          },
          "projectGuid": {
            "type": "string"
          },
          "projectName": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "ragStatus": {
            "type": "string"
          },
          "dueDate": {
            "type": "number"
          },
          "daysToDue": {
            "type": "integer"
          }
        }
      },
      "PortfolioImpactAggregate": {
        "type": "object",
        "properties": {
          "openImpactCount": {
            "type": "integer"
          },
          "openRiskCount": {
            "type": "integer"
          },
          "openIssueCount": {
            "type": "integer"
          },
          "openHighSeverityCount": {
            "type": "integer"
          },
          "keyItems": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PortfolioImpactSummaryItem"
            }
          }
        }
      },
      "PortfolioImpactSummaryItem": {
        "type": "object",
        "properties": {
          "impactGuid": {
            "type": "string"
          },
          "projectGuid": {
            "type": "string"
          },
          "projectName": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "ragStatus": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "dueDate": {
            "type": "number"
          }
        }
      }
    }
  }
}