{
  "openapi": "3.1.0",
  "info": {
    "title": "Release Cartographer API",
    "description": "\n### DevSecOps Release Telemetry & Decision Control Plane\n\nRelease Cartographer is a GitLab-native mission control engine that maps, verifies,\nand audits software releases across all nine DevSecOps stages:\n\n**Plan -> Create -> Verify -> Package -> Secure -> Release -> Configure -> Monitor -> Govern**\n\n* **Interactive Cartography**: Live visual dashboard rendering stage badges and state transitions.\n* **Autonomous Remediation**: Integrates with GitLab Duo Agent Platform for self-healing CI pipelines.\n* **Deterministic Decision Records**: Machine-readable governance audit certificates.\n* **Model Context Protocol (MCP)**: Native AI agent tool discovery and execution via JSON-RPC 2.0.\n",
    "contact": {
      "name": "Release Cartographer Team",
      "url": "https://gitlab.com/gitlab-ai-hackathon/transcend-october-2026/43583926/showcase"
    },
    "license": {
      "name": "MIT License",
      "url": "https://opensource.org/licenses/MIT"
    },
    "version": "0.1.0"
  },
  "paths": {
    "/health": {
      "get": {
        "tags": [
          "System Health"
        ],
        "summary": "Get Service Health & Version Metadata",
        "description": "Returns operational status and active build version identifier from environment.",
        "operationId": "health_health_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/schema/download": {
      "get": {
        "tags": [
          "System Health"
        ],
        "summary": "Download OpenAPI 3.1 Specification",
        "description": "Export the complete OpenAPI 3.1 JSON schema as a downloadable file.",
        "operationId": "download_schema_schema_download_get",
        "responses": {
          "200": {
            "description": "Successful Response"
          }
        }
      }
    },
    "/": {
      "get": {
        "tags": [
          "Dashboard"
        ],
        "summary": "Interactive Release Dashboard",
        "description": "Render the visual DevSecOps release map with responsive theme support and event simulator.",
        "operationId": "index__get",
        "parameters": [
          {
            "name": "release_id",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Release identifier to display on the cartography map",
              "default": "demo",
              "title": "Release Id"
            },
            "description": "Release identifier to display on the cartography map"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/dashboard/{release_id}": {
      "get": {
        "tags": [
          "Dashboard"
        ],
        "summary": "View Release Dashboard by ID",
        "description": "Render the visual DevSecOps release map for a specific release ID.",
        "operationId": "dashboard_dashboard__release_id__get",
        "parameters": [
          {
            "name": "release_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Target release identifier",
              "examples": [
                "demo"
              ],
              "title": "Release Id"
            },
            "description": "Target release identifier"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/events": {
      "post": {
        "tags": [
          "Telemetry"
        ],
        "summary": "Publish Lifecycle Stage Event",
        "description": "Ingest an automated lifecycle event emitted by a CI/CD job, security scanner, or release operator.",
        "operationId": "add_event_events_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EventRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object",
                  "title": "Response Add Event Events Post"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/lifecycle/{release_id}": {
      "get": {
        "tags": [
          "Telemetry"
        ],
        "summary": "Get Release Lifecycle Summary",
        "description": "Compute the deterministic 9-stage DevSecOps readiness summary and stage details for a release.",
        "operationId": "lifecycle_lifecycle__release_id__get",
        "parameters": [
          {
            "name": "release_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Release identifier to audit",
              "examples": [
                "demo"
              ],
              "title": "Release Id"
            },
            "description": "Release identifier to audit"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LifecycleSummary"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/events/{release_id}": {
      "delete": {
        "tags": [
          "Telemetry"
        ],
        "summary": "Clear Release Events",
        "description": "Purge in-memory telemetry events for a specific release identifier.",
        "operationId": "clear_events_events__release_id__delete",
        "parameters": [
          {
            "name": "release_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Release identifier to purge",
              "examples": [
                "demo"
              ],
              "title": "Release Id"
            },
            "description": "Release identifier to purge"
          }
        ],
        "responses": {
          "204": {
            "description": "Successful Response"
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "tags": [
          "MCP Server"
        ],
        "summary": "Model Context Protocol (MCP) JSON-RPC Endpoint",
        "description": "Standard JSON-RPC 2.0 endpoint enabling AI agents (e.g. GitLab Duo) to query release status, log telemetry, and formulate governance decisions.",
        "operationId": "mcp_endpoint_mcp_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JsonRpcRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful JSON-RPC response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object",
                  "title": "Response Mcp Endpoint Mcp Post"
                },
                "example": {
                  "jsonrpc": "2.0",
                  "id": 1,
                  "result": {
                    "content": [
                      {
                        "type": "text",
                        "text": "{'release_id': 'demo', 'overall': 'ready', 'completed': 9, 'total': 9}"
                      }
                    ]
                  }
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "EventRequest": {
        "properties": {
          "release_id": {
            "type": "string",
            "title": "Release Id",
            "description": "Unique release identifier or commit SHA",
            "examples": [
              "release-2026-v1"
            ]
          },
          "stage": {
            "$ref": "#/components/schemas/Stage",
            "description": "DevSecOps lifecycle stage",
            "examples": [
              "verify"
            ]
          },
          "status": {
            "type": "string",
            "title": "Status",
            "description": "Execution outcome: passed, failed, or pending",
            "examples": [
              "passed"
            ]
          },
          "detail": {
            "type": "string",
            "title": "Detail",
            "description": "Descriptive message or audit detail",
            "default": "",
            "examples": [
              "Unit test suite passed"
            ]
          }
        },
        "type": "object",
        "required": [
          "release_id",
          "stage",
          "status"
        ],
        "title": "EventRequest"
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
          }
        },
        "type": "object",
        "title": "HTTPValidationError"
      },
      "HealthResponse": {
        "properties": {
          "status": {
            "type": "string",
            "title": "Status",
            "description": "Operational status of the service",
            "examples": [
              "ok"
            ]
          },
          "service": {
            "type": "string",
            "title": "Service",
            "description": "Service identifier",
            "examples": [
              "release-cartographer"
            ]
          },
          "version": {
            "type": "string",
            "title": "Version",
            "description": "Active build version or commit SHA",
            "examples": [
              "0bcd96a"
            ]
          }
        },
        "type": "object",
        "required": [
          "status",
          "service",
          "version"
        ],
        "title": "HealthResponse"
      },
      "JsonRpcRequest": {
        "properties": {
          "jsonrpc": {
            "type": "string",
            "title": "Jsonrpc",
            "description": "JSON-RPC protocol version",
            "default": "2.0",
            "examples": [
              "2.0"
            ]
          },
          "id": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Id",
            "description": "Request identifier echoed in the response",
            "default": 1,
            "examples": [
              1
            ]
          },
          "method": {
            "type": "string",
            "title": "Method",
            "description": "JSON-RPC method: initialize, tools/list, tools/call, or ping",
            "examples": [
              "tools/call"
            ]
          },
          "params": {
            "additionalProperties": true,
            "type": "object",
            "title": "Params",
            "description": "Method parameters",
            "examples": [
              {
                "arguments": {
                  "release_id": "demo"
                },
                "name": "get_release_status"
              }
            ]
          }
        },
        "type": "object",
        "required": [
          "method"
        ],
        "title": "JsonRpcRequest"
      },
      "LifecycleSummary": {
        "properties": {
          "release_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Release Id",
            "description": "Release identifier",
            "examples": [
              "release-2026-v1"
            ]
          },
          "overall": {
            "type": "string",
            "title": "Overall",
            "description": "Overall readiness: ready, in_progress, or attention",
            "examples": [
              "ready"
            ]
          },
          "completed": {
            "type": "integer",
            "title": "Completed",
            "description": "Number of completed stages",
            "examples": [
              9
            ]
          },
          "total": {
            "type": "integer",
            "title": "Total",
            "description": "Total DevSecOps stages",
            "examples": [
              9
            ]
          },
          "stages": {
            "additionalProperties": {
              "$ref": "#/components/schemas/StageStatus"
            },
            "type": "object",
            "title": "Stages",
            "description": "Map of stage names to status details"
          }
        },
        "type": "object",
        "required": [
          "release_id",
          "overall",
          "completed",
          "total",
          "stages"
        ],
        "title": "LifecycleSummary"
      },
      "Stage": {
        "type": "string",
        "enum": [
          "plan",
          "create",
          "verify",
          "package",
          "secure",
          "release",
          "configure",
          "monitor",
          "govern"
        ],
        "title": "Stage"
      },
      "StageStatus": {
        "properties": {
          "status": {
            "type": "string",
            "title": "Status",
            "description": "Stage status: passed, failed, or pending",
            "examples": [
              "passed"
            ]
          },
          "detail": {
            "type": "string",
            "title": "Detail",
            "description": "Stage telemetry message",
            "examples": [
              "Pytest unit tests green"
            ]
          }
        },
        "type": "object",
        "required": [
          "status",
          "detail"
        ],
        "title": "StageStatus"
      },
      "ValidationError": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      }
    }
  },
  "tags": [
    {
      "name": "System Health",
      "description": "Operational health checks and release version verification."
    },
    {
      "name": "Telemetry",
      "description": "Ingest and retrieve release stage events and lifecycle evaluations."
    },
    {
      "name": "Dashboard",
      "description": "Interactive HTML release cartography maps and telemetry simulator."
    },
    {
      "name": "MCP Server",
      "description": "Model Context Protocol JSON-RPC endpoints for AI agent orchestration."
    }
  ]
}