{
  "openapi": "3.0.0",
  "paths": {
    "/scans": {
      "post": {
        "operationId": "RestScanController_create",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RestCreateScanDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestCreateScanResponseDto"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient credits"
          }
        },
        "summary": "Trigger a pentest scan",
        "tags": ["REST API - Scans"]
      },
      "get": {
        "operationId": "RestScanController_list",
        "parameters": [
          {
            "name": "page",
            "required": false,
            "in": "query",
            "description": "The page number to retrieve.",
            "schema": {
              "default": 1,
              "type": "number"
            }
          },
          {
            "name": "limit",
            "required": false,
            "in": "query",
            "description": "The number of items to retrieve per page.",
            "schema": {
              "default": 100,
              "type": "number"
            }
          },
          {
            "name": "scan_type",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["pr", "full"]
            }
          },
          {
            "name": "status",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "running",
                "completed",
                "failed",
                "stopped",
                "cancelled",
                "skipped",
                "pending_verification",
                "pending_triage",
                "draft",
                "estimating",
                "estimated"
              ]
            }
          },
          {
            "name": "sort_by",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["created_at", "updated_at", "status"]
            }
          },
          {
            "name": "sort_order",
            "required": false,
            "in": "query",
            "schema": {
              "default": "DESC",
              "type": "string",
              "enum": ["ASC", "DESC"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestScanListResponseDto"
                }
              }
            }
          }
        },
        "summary": "List scans with pagination and filters",
        "tags": ["REST API - Scans"]
      }
    },
    "/scans/{id}/stop": {
      "post": {
        "operationId": "RestScanController_stop",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestScanStatusResponseDto"
                }
              }
            }
          }
        },
        "summary": "Stop a running scan. Members can stop pentests they started and any PR scan; admins can stop any scan.",
        "tags": ["REST API - Scans"]
      }
    },
    "/scans/{id}/status": {
      "get": {
        "operationId": "RestScanController_getStatus",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestScanStatusResponseDto"
                }
              }
            }
          }
        },
        "summary": "Get scan status",
        "tags": ["REST API - Scans"]
      }
    },
    "/scans/{id}/findings/export": {
      "get": {
        "operationId": "RestScanController_exportFindings",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "format",
            "required": true,
            "in": "query",
            "description": "Export format",
            "schema": {
              "type": "string",
              "enum": ["json", "csv", "sarif"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": ""
          }
        },
        "summary": "Export findings for a scan",
        "tags": ["REST API - Scans"]
      }
    },
    "/scans/{id}/findings": {
      "get": {
        "operationId": "RestScanController_listScanFindings",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "required": false,
            "in": "query",
            "description": "The page number to retrieve.",
            "schema": {
              "default": 1,
              "type": "number"
            }
          },
          {
            "name": "limit",
            "required": false,
            "in": "query",
            "description": "The number of items to retrieve per page.",
            "schema": {
              "default": 100,
              "type": "number"
            }
          },
          {
            "name": "severity",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["critical", "high", "medium", "low", "info"]
            }
          },
          {
            "name": "state",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "open",
                "true_positive",
                "false_positive",
                "accepted_risk",
                "resolved",
                "closed"
              ]
            }
          },
          {
            "name": "scan_id",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "scan_type",
            "required": false,
            "in": "query",
            "description": "Filter by scan type across all scans associated with the finding.",
            "schema": {
              "type": "string",
              "enum": ["pr", "full"]
            }
          },
          {
            "name": "repo_url",
            "required": false,
            "in": "query",
            "description": "Filter by repository URL. Case-insensitive; a trailing slash or .git suffix is ignored.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "found_since",
            "required": false,
            "in": "query",
            "description": "Only include findings discovered on/after this ISO 8601 timestamp.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "found_until",
            "required": false,
            "in": "query",
            "description": "Only include findings discovered before this ISO 8601 timestamp.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort_by",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["found_at", "updated_at", "severity"]
            }
          },
          {
            "name": "sort_order",
            "required": false,
            "in": "query",
            "schema": {
              "default": "DESC",
              "type": "string",
              "enum": ["ASC", "DESC"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestFindingListResponseDto"
                }
              }
            }
          }
        },
        "summary": "List findings for a specific scan",
        "tags": ["REST API - Scans"]
      }
    },
    "/scans/{id}": {
      "get": {
        "operationId": "RestScanController_getById",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestScanResponseDto"
                }
              }
            }
          }
        },
        "summary": "Get scan by UUID",
        "tags": ["REST API - Scans"]
      }
    },
    "/findings": {
      "get": {
        "operationId": "RestFindingController_list",
        "parameters": [
          {
            "name": "page",
            "required": false,
            "in": "query",
            "description": "The page number to retrieve.",
            "schema": {
              "default": 1,
              "type": "number"
            }
          },
          {
            "name": "limit",
            "required": false,
            "in": "query",
            "description": "The number of items to retrieve per page.",
            "schema": {
              "default": 100,
              "type": "number"
            }
          },
          {
            "name": "severity",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["critical", "high", "medium", "low", "info"]
            }
          },
          {
            "name": "state",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "open",
                "true_positive",
                "false_positive",
                "accepted_risk",
                "resolved",
                "closed"
              ]
            }
          },
          {
            "name": "scan_id",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "scan_type",
            "required": false,
            "in": "query",
            "description": "Filter by scan type across all scans associated with the finding.",
            "schema": {
              "type": "string",
              "enum": ["pr", "full"]
            }
          },
          {
            "name": "repo_url",
            "required": false,
            "in": "query",
            "description": "Filter by repository URL. Case-insensitive; a trailing slash or .git suffix is ignored.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "found_since",
            "required": false,
            "in": "query",
            "description": "Only include findings discovered on/after this ISO 8601 timestamp.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "found_until",
            "required": false,
            "in": "query",
            "description": "Only include findings discovered before this ISO 8601 timestamp.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort_by",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["found_at", "updated_at", "severity"]
            }
          },
          {
            "name": "sort_order",
            "required": false,
            "in": "query",
            "schema": {
              "default": "DESC",
              "type": "string",
              "enum": ["ASC", "DESC"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestFindingListResponseDto"
                }
              }
            }
          }
        },
        "summary": "List findings with pagination and filters",
        "tags": ["REST API - Findings"]
      }
    },
    "/findings/counts": {
      "get": {
        "operationId": "RestFindingController_counts",
        "parameters": [
          {
            "name": "severity",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["critical", "high", "medium", "low", "info"]
            }
          },
          {
            "name": "state",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "open",
                "true_positive",
                "false_positive",
                "accepted_risk",
                "resolved",
                "closed"
              ]
            }
          },
          {
            "name": "scan_id",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "scan_type",
            "required": false,
            "in": "query",
            "description": "Filter by scan type across all scans associated with the finding.",
            "schema": {
              "type": "string",
              "enum": ["pr", "full"]
            }
          },
          {
            "name": "repo_url",
            "required": false,
            "in": "query",
            "description": "Filter by repository URL. Case-insensitive; a trailing slash or .git suffix is ignored.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "found_since",
            "required": false,
            "in": "query",
            "description": "Only include findings discovered on/after this ISO 8601 timestamp.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "found_until",
            "required": false,
            "in": "query",
            "description": "Only include findings discovered before this ISO 8601 timestamp.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestFindingCountsResponseDto"
                }
              }
            }
          }
        },
        "summary": "Count findings matching the list filters, by severity, state and repository",
        "tags": ["REST API - Findings"]
      }
    },
    "/findings/export": {
      "get": {
        "operationId": "RestFindingController_exportFindings",
        "parameters": [
          {
            "name": "page",
            "required": false,
            "in": "query",
            "description": "The page number to retrieve.",
            "schema": {
              "default": 1,
              "type": "number"
            }
          },
          {
            "name": "limit",
            "required": false,
            "in": "query",
            "description": "The number of items to retrieve per page.",
            "schema": {
              "default": 100,
              "type": "number"
            }
          },
          {
            "name": "severity",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["critical", "high", "medium", "low", "info"]
            }
          },
          {
            "name": "state",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "open",
                "true_positive",
                "false_positive",
                "accepted_risk",
                "resolved",
                "closed"
              ]
            }
          },
          {
            "name": "scan_id",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "scan_type",
            "required": false,
            "in": "query",
            "description": "Filter by scan type across all scans associated with the finding.",
            "schema": {
              "type": "string",
              "enum": ["pr", "full"]
            }
          },
          {
            "name": "repo_url",
            "required": false,
            "in": "query",
            "description": "Filter by repository URL. Case-insensitive; a trailing slash or .git suffix is ignored.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "found_since",
            "required": false,
            "in": "query",
            "description": "Only include findings discovered on/after this ISO 8601 timestamp.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "found_until",
            "required": false,
            "in": "query",
            "description": "Only include findings discovered before this ISO 8601 timestamp.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort_by",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["found_at", "updated_at", "severity"]
            }
          },
          {
            "name": "sort_order",
            "required": false,
            "in": "query",
            "schema": {
              "default": "DESC",
              "type": "string",
              "enum": ["ASC", "DESC"]
            }
          },
          {
            "name": "format",
            "required": true,
            "in": "query",
            "description": "Export format",
            "schema": {
              "type": "string",
              "enum": ["json", "csv", "sarif"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": ""
          }
        },
        "summary": "Export findings as JSON, CSV, or SARIF, optionally filtered by repository",
        "tags": ["REST API - Findings"]
      }
    },
    "/findings/{id}": {
      "patch": {
        "operationId": "RestFindingController_update",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Finding UUID or display id (KEY-FD-NUMBER, e.g. HAC-FD-1104)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RestUpdateFindingDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestUpdateFindingResponseDto"
                }
              }
            }
          }
        },
        "summary": "Update finding state, severity, and/or duplicate link",
        "tags": ["REST API - Findings"]
      },
      "get": {
        "operationId": "RestFindingController_getById",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Finding UUID or display id (KEY-FD-NUMBER, e.g. HAC-FD-1104)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestFindingDetailResponseDto"
                }
              }
            }
          }
        },
        "summary": "Get finding details",
        "tags": ["REST API - Findings"]
      }
    },
    "/findings/{id}/comments": {
      "post": {
        "operationId": "RestFindingController_addComment",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Finding UUID or display id (KEY-FD-NUMBER, e.g. HAC-FD-1104)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RestAddCommentDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestAddCommentResponseDto"
                }
              }
            }
          }
        },
        "summary": "Add a comment to a finding",
        "tags": ["REST API - Findings"]
      }
    },
    "/findings/{id}/remediate": {
      "post": {
        "operationId": "RestFindingController_remediate",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Finding UUID or display id (KEY-FD-NUMBER, e.g. HAC-FD-1104)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestStartRemediationResponseDto"
                }
              }
            }
          }
        },
        "summary": "Generate a fix for a finding and open it as a pull request, as the web app's Remediate button does",
        "tags": ["REST API - Findings"]
      }
    },
    "/findings/{id}/remediation": {
      "get": {
        "operationId": "RestFindingController_getRemediation",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Finding UUID or display id (KEY-FD-NUMBER, e.g. HAC-FD-1104)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestFindingRemediationDto"
                }
              }
            }
          }
        },
        "summary": "Get the finding's latest fix run",
        "tags": ["REST API - Findings"]
      }
    },
    "/cost-estimations": {
      "post": {
        "operationId": "RestCostEstimationController_create",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateCostEstimationDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CostEstimationResponseDto"
                }
              }
            }
          }
        },
        "summary": "Create a cost estimation for one or more repos",
        "tags": ["REST API - Cost Estimations"]
      },
      "get": {
        "operationId": "RestCostEstimationController_list",
        "parameters": [
          {
            "name": "limit",
            "required": false,
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "offset",
            "required": false,
            "in": "query",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestCostEstimationListResponseDto"
                }
              }
            }
          }
        },
        "summary": "List cost estimations",
        "tags": ["REST API - Cost Estimations"]
      }
    },
    "/cost-estimations/{id}": {
      "get": {
        "operationId": "RestCostEstimationController_findOne",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CostEstimationResponseDto"
                }
              }
            }
          }
        },
        "summary": "Get cost estimation details",
        "tags": ["REST API - Cost Estimations"]
      }
    },
    "/repos": {
      "get": {
        "operationId": "RestRepoController_list",
        "parameters": [],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MergedReposResponseDto"
                }
              }
            }
          }
        },
        "summary": "List repositories from all connected providers, including whether PR scans are enabled",
        "tags": ["REST API - Repos"]
      }
    },
    "/repos/pr-reviews": {
      "post": {
        "operationId": "RestRepoController_setPrReviews",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RepositoryIdBatchDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RepositoryBatchResultDto"
                }
              }
            }
          }
        },
        "summary": "Turn PR/MR reviews on or off for repositories, by their id from the repository list. A repository must be selected for Hacktron access before its reviews can be turned on.",
        "tags": ["REST API - Repos"]
      }
    },
    "/hfw/verdicts/batch": {
      "post": {
        "description": "Public, fast-mode HFW batch verdict proxy. This endpoint is intentionally scoped to feed-backed verdicts and can be moved behind X-Api-Key later.",
        "operationId": "RestHfwController_getBatchVerdicts",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RestHfwBatchRequestDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestHfwBatchResponseDto"
                }
              }
            }
          }
        },
        "security": [],
        "summary": "Get fast dependency verdicts for landing and GitHub Action scans",
        "tags": ["REST API - HFW"]
      }
    },
    "/hfw/osv/feed": {
      "get": {
        "operationId": "RestHfwController_getOsvFeed",
        "parameters": [
          {
            "name": "limit",
            "required": false,
            "in": "query",
            "schema": {
              "minimum": 1,
              "maximum": 200,
              "default": 200,
              "type": "number"
            }
          },
          {
            "name": "offset",
            "required": false,
            "in": "query",
            "schema": {
              "minimum": 0,
              "default": 0,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestHfwOsvFeedResponseDto"
                }
              }
            }
          }
        },
        "security": [],
        "summary": "List known-malware feed entries for package sitemap generation",
        "tags": ["REST API - HFW"]
      }
    },
    "/hfw/verdict/{ecosystem}/{packageName}": {
      "get": {
        "description": "Public, fast-mode HFW verdict proxy. This endpoint is intentionally scoped to feed-backed verdicts and can be moved behind X-Api-Key later.",
        "operationId": "RestHfwController_getPackageVerdict",
        "parameters": [
          {
            "name": "ecosystem",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string",
              "enum": ["npm", "pypi"]
            }
          },
          {
            "name": "packageName",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "version",
            "required": true,
            "in": "query",
            "description": "Package version to check",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "wait_seconds",
            "required": false,
            "in": "query",
            "description": "Seconds to wait for an upstream verdict. Fast mode normally returns immediately.",
            "schema": {
              "minimum": 0,
              "maximum": 8,
              "default": 0,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestHfwVerdictResponseDto"
                }
              }
            }
          }
        },
        "security": [],
        "summary": "Get a fast dependency verdict for GitHub Action scans",
        "tags": ["REST API - HFW"]
      }
    },
    "/hfw/verdict/{ecosystem}/{scope}/{packageName}": {
      "get": {
        "operationId": "RestHfwController_getScopedNpmPackageVerdict",
        "parameters": [
          {
            "name": "ecosystem",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string",
              "enum": ["npm", "pypi"]
            }
          },
          {
            "name": "packageName",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "scope",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "version",
            "required": true,
            "in": "query",
            "description": "Package version to check",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "wait_seconds",
            "required": false,
            "in": "query",
            "description": "Seconds to wait for an upstream verdict. Fast mode normally returns immediately.",
            "schema": {
              "minimum": 0,
              "maximum": 8,
              "default": 0,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestHfwVerdictResponseDto"
                }
              }
            }
          }
        },
        "security": [],
        "summary": "Get a fast dependency verdict for scoped npm GitHub Action scans",
        "tags": ["REST API - HFW"]
      }
    },
    "/pentests": {
      "post": {
        "operationId": "RestPentestController_create",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RestCreatePentestDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestPentestResponseDto"
                }
              }
            }
          }
        },
        "summary": "Create a draft pentest of repositories or uploaded archives, optionally with live sites",
        "tags": ["REST API - Pentests"]
      }
    },
    "/pentests/{id}": {
      "patch": {
        "operationId": "RestPentestController_update",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RestUpdatePentestDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestPentestResponseDto"
                }
              }
            }
          }
        },
        "summary": "Change a pentest that has not started. Changing its repositories clears the estimate.",
        "tags": ["REST API - Pentests"]
      },
      "delete": {
        "operationId": "RestPentestController_discard",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestDiscardPentestResponseDto"
                }
              }
            }
          }
        },
        "summary": "Discard a pentest that has not started",
        "tags": ["REST API - Pentests"]
      }
    },
    "/pentests/{id}/login-checks": {
      "post": {
        "operationId": "RestPentestController_checkLogins",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "wait_seconds",
            "required": false,
            "in": "query",
            "description": "Wait up to this many seconds for the work to finish before answering",
            "schema": {
              "minimum": 0,
              "maximum": 50,
              "default": 0,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestPentestResponseDto"
                }
              }
            }
          },
          "400": {
            "description": "The pentest has no login targets"
          }
        },
        "summary": "Check that Hacktron can sign in to each login target, which it must before the pentest starts",
        "tags": ["REST API - Pentests"]
      }
    },
    "/pentests/{id}/estimate": {
      "post": {
        "operationId": "RestPentestController_estimate",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestPentestResponseDto"
                }
              }
            }
          }
        },
        "summary": "Price a draft pentest; read it at GET /cost-estimations/{cost_estimation_id}",
        "tags": ["REST API - Pentests"]
      }
    },
    "/pentests/{id}/start": {
      "post": {
        "operationId": "RestPentestController_start",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RestStartPentestDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestPentestResponseDto"
                }
              }
            }
          },
          "400": {
            "description": "A login target has no passing login check from the last hour"
          },
          "402": {
            "description": "Insufficient credits"
          },
          "409": {
            "description": "expected_credits no longer matches the total; read the estimate again and confirm the new total"
          }
        },
        "summary": "Start an estimated pentest, spending the confirmed credits (organization admins only)",
        "tags": ["REST API - Pentests"]
      }
    },
    "/archives/uploads": {
      "post": {
        "operationId": "RestArchiveController_requestUpload",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RequestUploadDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RequestUploadResponseDto"
                }
              }
            }
          }
        },
        "summary": "Get a URL to upload a code archive (.zip, .7z or .tar.gz) to, then pentest it as a repo with source upload",
        "tags": ["REST API - Archives"]
      }
    },
    "/credits": {
      "get": {
        "operationId": "RestCreditController_balance",
        "parameters": [],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PentestCreditBalanceResponseDto"
                }
              }
            }
          }
        },
        "summary": "The organization's pentest credit balance",
        "tags": ["REST API - Credits"]
      }
    },
    "/credits/automation": {
      "get": {
        "operationId": "RestCreditController_automationBalance",
        "parameters": [],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationCreditBalanceResponseDto"
                }
              }
            }
          }
        },
        "summary": "The organization's automation credit balance, which fixes are charged to",
        "tags": ["REST API - Credits"]
      }
    },
    "/pr-review-settings": {
      "get": {
        "operationId": "RestPrReviewSettingsController_get",
        "parameters": [],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestPrReviewSettingsDto"
                }
              }
            }
          }
        },
        "summary": "Get the organization's PR/MR review settings: whether reviews post comments, the severity that fails the PR check, and which PRs are reviewed",
        "tags": ["REST API - Repos"]
      },
      "patch": {
        "operationId": "RestPrReviewSettingsController_update",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RestPrReviewSettingsDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestPrReviewSettingsDto"
                }
              }
            }
          }
        },
        "summary": "Change the organization's PR/MR review settings. Only the fields sent change; null turns off the fail-on severity or clears a filter. A repository's .hacktron/config.yaml overrides these.",
        "tags": ["REST API - Repos"]
      }
    },
    "/pull-requests": {
      "get": {
        "operationId": "RestPullRequestController_list",
        "parameters": [
          {
            "name": "repository_id",
            "required": false,
            "in": "query",
            "description": "Id from the repository list. Without it, open pull requests across the organization's enabled repositories are listed.",
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          },
          {
            "name": "mine",
            "required": false,
            "in": "query",
            "description": "Only pull requests the caller opened, among each repository's most recently updated open pull requests, matched through the caller's source control accounts linked to Hacktron; with none linked nothing matches",
            "schema": {
              "default": false,
              "type": "boolean"
            }
          },
          {
            "name": "limit",
            "required": false,
            "in": "query",
            "description": "At most this many, across repositories. Not paginated: narrow with repository_id or mine",
            "schema": {
              "minimum": 1,
              "maximum": 50,
              "default": 20,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestPullRequestListDto"
                }
              }
            }
          },
          "400": {
            "description": "The repository isn't enabled for Hacktron, or its provider has no PR reviews here"
          },
          "404": {
            "description": "The repository isn't connected to the organization"
          },
          "503": {
            "description": "The repository's provider could not be read; try again later"
          }
        },
        "summary": "List open pull and merge requests of a connected repository, or across up to 20 of the organization's enabled repositories, most recently updated first",
        "tags": ["REST API - Pull Requests"]
      }
    },
    "/pull-requests/details": {
      "get": {
        "operationId": "RestPullRequestController_get",
        "parameters": [
          {
            "name": "url",
            "required": false,
            "in": "query",
            "description": "The pull or merge request's web link. Give this, or repository_id and number.",
            "schema": {
              "example": "https://github.com/acme/api/pull/42",
              "type": "string"
            }
          },
          {
            "name": "repository_id",
            "required": false,
            "in": "query",
            "description": "Id from the repository list",
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          },
          {
            "name": "number",
            "required": false,
            "in": "query",
            "description": "The pull or merge request number in that repository",
            "schema": {
              "example": 42,
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestPullRequestDetailsDto"
                }
              }
            }
          },
          "400": {
            "description": "Not a pull request link, a repository not enabled for Hacktron, or a GitHub repository connected with a personal access token"
          },
          "404": {
            "description": "The pull request, or its repository in the organization, wasn't found"
          },
          "503": {
            "description": "The repository's provider could not be read; try again later"
          }
        },
        "summary": "Get a pull or merge request by its link, or by repository id and number, with Hacktron's review of its head commit",
        "tags": ["REST API - Pull Requests"]
      }
    },
    "/pull-requests/review": {
      "post": {
        "operationId": "RestPullRequestController_startReview",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RestStartPrReviewDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestStartPrReviewResponseDto"
                }
              }
            }
          },
          "400": {
            "description": "Not a pull request link, a repository not enabled for Hacktron, or a GitHub repository connected with a personal access token"
          },
          "404": {
            "description": "The pull request, or its repository in the organization, wasn't found"
          },
          "409": {
            "description": "The pull request is closed or merged"
          },
          "422": {
            "description": "The review could not run; the message says why. A failed start can be retried"
          },
          "503": {
            "description": "The repository's provider could not be read; try again later"
          }
        },
        "summary": "Review a pull or merge request, as if a repository member commented @hacktronai review on it. It runs on the head commit, posts on the pull request as the organization's settings say, and returns the existing review when that commit already has one.",
        "tags": ["REST API - Pull Requests"]
      }
    },
    "/code-workspaces": {
      "post": {
        "operationId": "RestSecurityArchitectController_openWorkspace",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RestOpenCodeWorkspaceDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestCodeWorkspaceDto"
                }
              }
            }
          },
          "400": {
            "description": "The repository isn't enabled for Hacktron, or its provider has no code workspaces"
          },
          "404": {
            "description": "The repository or pull request wasn't found"
          },
          "429": {
            "description": "The organization has 25 workspaces open, the most at once, or this one is busy with other queries"
          },
          "503": {
            "description": "The repository's provider could not be read, or code workspaces aren't responding; try again later"
          }
        },
        "summary": "Open a read-only code workspace on a connected repository at a branch, tag or commit, or on a pull request's head commit, shared by the organization for that commit",
        "tags": ["REST API - Security Architect"]
      }
    },
    "/code-workspaces/{workspace_id}/query": {
      "post": {
        "operationId": "RestSecurityArchitectController_queryWorkspace",
        "parameters": [
          {
            "name": "workspace_id",
            "required": true,
            "in": "path",
            "description": "workspace_id from opening a code workspace",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RestCodeQueryDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestCodeQueryResultDto"
                }
              }
            }
          },
          "400": {
            "description": "The query is invalid, such as a path outside the repository or a diff outside a pull request"
          },
          "404": {
            "description": "The workspace has closed; open it again"
          },
          "409": {
            "description": "The workspace failed or is closing; open it again"
          },
          "429": {
            "description": "The workspace is busy with other queries; try again in a few seconds"
          }
        },
        "summary": "Run a command in an open workspace, or search, read, list, diff, log or blame its code with a fixed command",
        "tags": ["REST API - Security Architect"]
      }
    },
    "/context-documents": {
      "get": {
        "operationId": "RestSecurityArchitectController_listContextDocuments",
        "parameters": [
          {
            "name": "repository_id",
            "required": true,
            "in": "query",
            "description": "Id from the repository list",
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestContextDocumentListDto"
                }
              }
            }
          }
        },
        "summary": "List a repository's threat model, its applications' threat models, and the context documents uploaded for it",
        "tags": ["REST API - Security Architect"]
      },
      "post": {
        "operationId": "RestSecurityArchitectController_addContextDocument",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RestAddContextDocumentDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestContextDocumentDto"
                }
              }
            }
          }
        },
        "summary": "Save markdown as a context document on a repository; the next threat model update folds it in",
        "tags": ["REST API - Security Architect"]
      }
    },
    "/context-documents/{id}": {
      "get": {
        "operationId": "RestSecurityArchitectController_readContextDocument",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestContextDocumentContentDto"
                }
              }
            }
          }
        },
        "summary": "Read a threat model or context document",
        "tags": ["REST API - Security Architect"]
      }
    },
    "/context-documents/{id}/edit": {
      "post": {
        "operationId": "RestSecurityArchitectController_editContextDocument",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RestEditContextDocumentDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestContextDocumentDto"
                }
              }
            }
          },
          "400": {
            "description": "A replacement's text isn't in the document exactly once, the edits change nothing, or the document isn't text"
          },
          "409": {
            "description": "The document changed while the edit was applied, such as by a threat model sync; read it again and redo the edit"
          }
        },
        "summary": "Edit a threat model or text context document in place with exact replacements or appended text. A threat model keeps the edited lines, so later syncs leave them alone.",
        "tags": ["REST API - Security Architect"]
      }
    },
    "/repositories/{id}/threat-model/sync": {
      "post": {
        "operationId": "RestSecurityArchitectController_updateThreatModel",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestThreatModelUpdateDto"
                }
              }
            }
          }
        },
        "summary": "Fold a repository's new context documents and triage feedback into its threat model, or build its first one from the code",
        "tags": ["REST API - Security Architect"]
      }
    },
    "/applications": {
      "get": {
        "operationId": "RestSecurityArchitectController_listApplications",
        "parameters": [],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApplicationListResponseDto"
                }
              }
            }
          }
        },
        "summary": "List the organization's applications",
        "tags": ["REST API - Security Architect"]
      },
      "post": {
        "operationId": "RestSecurityArchitectController_createApplication",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RestCreateApplicationDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApplicationResponseDto"
                }
              }
            }
          }
        },
        "summary": "Create an application from connected repositories; its threat model builds right away when every repository has one",
        "tags": ["REST API - Security Architect"]
      }
    },
    "/applications/{idOrSlug}/repositories": {
      "post": {
        "operationId": "RestSecurityArchitectController_addApplicationRepositories",
        "parameters": [
          {
            "name": "idOrSlug",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RestApplicationRepositoriesDto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApplicationRepoListResponseDto"
                }
              }
            }
          }
        },
        "summary": "Add connected repositories to an application",
        "tags": ["REST API - Security Architect"]
      }
    },
    "/applications/{idOrSlug}/threat-model/sync": {
      "post": {
        "operationId": "RestSecurityArchitectController_updateApplicationThreatModel",
        "parameters": [
          {
            "name": "idOrSlug",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ThreatModelSyncResponseDto"
                }
              }
            }
          }
        },
        "summary": "Rebuild an application's threat model from its repositories' threat models, building any missing ones first",
        "tags": ["REST API - Security Architect"]
      }
    },
    "/scans/{id}/report": {
      "get": {
        "operationId": "RestSecurityArchitectController_pentestReport",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RestPentestReportDto"
                }
              }
            }
          }
        },
        "summary": "A pentest's executive summary and what it covered: each application's attack surfaces and entry points",
        "tags": ["REST API - Security Architect"]
      }
    }
  },
  "info": {
    "title": "Hacktron REST API",
    "description": "Public REST API for programmatic access to Hacktron",
    "version": "1.0",
    "contact": {}
  },
  "tags": [],
  "servers": [
    {
      "url": "https://api.hacktron.ai/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "api-key": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key"
      }
    },
    "schemas": {
      "RestRepoDto": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "Repository URL"
          },
          "branch": {
            "type": "string",
            "description": "Branch name"
          },
          "source": {
            "type": "string",
            "description": "Repository source",
            "enum": ["connected", "public", "upload"],
            "default": "connected"
          }
        },
        "required": ["url", "branch"]
      },
      "RestCreateScanDto": {
        "type": "object",
        "properties": {
          "cost_estimation_id": {
            "type": "string",
            "description": "Completed cost estimation UUID"
          },
          "repos": {
            "description": "Repositories to scan",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RestRepoDto"
            }
          },
          "target_urls": {
            "description": "Target URLs for pentest",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "auth_instructions": {
            "type": "string",
            "description": "Target websites and browser login instructions, including URLs and credentials",
            "maxLength": 2000
          },
          "custom_context": {
            "type": "string",
            "description": "Custom context for the pentest",
            "maxLength": 2000
          },
          "context_document_ids": {
            "description": "Context document UUIDs to include",
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": ["cost_estimation_id", "repos"]
      },
      "RestCreateScanResponseDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "task_id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": ["id", "task_id", "status", "message"]
      },
      "RestScanStatusResponseDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "task_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "running",
              "completed",
              "failed",
              "stopped",
              "cancelled",
              "skipped",
              "pending_verification",
              "pending_triage",
              "draft",
              "estimating",
              "estimated"
            ]
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          }
        },
        "required": ["id", "task_id", "status", "created_at", "updated_at"]
      },
      "RestScanFindingsSummaryDto": {
        "type": "object",
        "properties": {
          "critical": {
            "type": "number"
          },
          "high": {
            "type": "number"
          },
          "medium": {
            "type": "number"
          },
          "low": {
            "type": "number"
          },
          "info": {
            "type": "number"
          }
        },
        "required": ["critical", "high", "medium", "low", "info"]
      },
      "RestScanResponseDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "task_id": {
            "type": "string"
          },
          "scan_type": {
            "type": "string",
            "enum": ["pr", "full"]
          },
          "status": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "repo_url": {
            "type": "string",
            "nullable": true
          },
          "branch": {
            "type": "string",
            "nullable": true
          },
          "pr_number": {
            "type": "number",
            "nullable": true
          },
          "target_urls": {
            "nullable": true,
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "findings_summary": {
            "$ref": "#/components/schemas/RestScanFindingsSummaryDto"
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "task_id",
          "scan_type",
          "status",
          "name",
          "repo_url",
          "branch",
          "pr_number",
          "target_urls",
          "findings_summary",
          "created_at",
          "updated_at"
        ]
      },
      "RestScanListResponseDto": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RestScanResponseDto"
            }
          },
          "total": {
            "type": "number"
          },
          "page": {
            "type": "number"
          },
          "limit": {
            "type": "number"
          }
        },
        "required": ["data", "total", "page", "limit"]
      },
      "RestFindingResponseDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Finding UUID"
          },
          "display_id": {
            "type": "string",
            "description": "Human-readable id (KEY-FD-NUMBER).",
            "example": "HAC-FD-1104"
          },
          "number": {
            "type": "integer",
            "description": "Per-organization sequence number behind display_id.",
            "example": 1104
          },
          "title": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "severity": {
            "type": "string",
            "enum": ["critical", "high", "medium", "low", "info"]
          },
          "state": {
            "type": "string",
            "enum": [
              "open",
              "true_positive",
              "false_positive",
              "accepted_risk",
              "resolved",
              "closed"
            ]
          },
          "description": {
            "type": "string"
          },
          "affected_file": {
            "type": "string"
          },
          "affected_code": {
            "type": "string"
          },
          "proof_of_concept": {
            "type": "string",
            "nullable": true
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "scan_id": {
            "type": "string",
            "nullable": true
          },
          "found_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          },
          "resolved_at": {
            "type": "string",
            "nullable": true,
            "description": "Timestamp of the most recent transition to resolved (ISO 8601). Null if never resolved."
          }
        },
        "required": [
          "id",
          "display_id",
          "number",
          "title",
          "category",
          "severity",
          "state",
          "description",
          "affected_file",
          "affected_code",
          "proof_of_concept",
          "tags",
          "scan_id",
          "found_at",
          "updated_at",
          "resolved_at"
        ]
      },
      "RestFindingListResponseDto": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RestFindingResponseDto"
            }
          },
          "total": {
            "type": "number"
          },
          "page": {
            "type": "number"
          },
          "limit": {
            "type": "number"
          }
        },
        "required": ["data", "total", "page", "limit"]
      },
      "RestSeverityCountsDto": {
        "type": "object",
        "properties": {
          "critical": {
            "type": "number"
          },
          "high": {
            "type": "number"
          },
          "medium": {
            "type": "number"
          },
          "low": {
            "type": "number"
          },
          "info": {
            "type": "number"
          }
        },
        "required": ["critical", "high", "medium", "low", "info"]
      },
      "RestStateCountsDto": {
        "type": "object",
        "properties": {
          "open": {
            "type": "number"
          },
          "true_positive": {
            "type": "number"
          },
          "false_positive": {
            "type": "number"
          },
          "accepted_risk": {
            "type": "number"
          },
          "resolved": {
            "type": "number"
          },
          "closed": {
            "type": "number"
          }
        },
        "required": [
          "open",
          "true_positive",
          "false_positive",
          "accepted_risk",
          "resolved",
          "closed"
        ]
      },
      "RestRepositoryFindingCountsDto": {
        "type": "object",
        "properties": {
          "repository": {
            "type": "string",
            "nullable": true,
            "description": "Repository URL, or null for findings with no repository"
          },
          "total": {
            "type": "number"
          },
          "by_severity": {
            "$ref": "#/components/schemas/RestSeverityCountsDto"
          }
        },
        "required": ["repository", "total", "by_severity"]
      },
      "RestFindingCountsResponseDto": {
        "type": "object",
        "properties": {
          "total": {
            "type": "number"
          },
          "by_severity": {
            "$ref": "#/components/schemas/RestSeverityCountsDto"
          },
          "by_state": {
            "$ref": "#/components/schemas/RestStateCountsDto"
          },
          "by_repository": {
            "description": "Most findings first",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RestRepositoryFindingCountsDto"
            }
          }
        },
        "required": ["total", "by_severity", "by_state", "by_repository"]
      },
      "RestUpdateFindingDto": {
        "type": "object",
        "properties": {
          "state": {
            "type": "string",
            "enum": [
              "open",
              "true_positive",
              "false_positive",
              "accepted_risk",
              "resolved",
              "closed"
            ],
            "description": "New finding state"
          },
          "severity": {
            "type": "string",
            "enum": ["critical", "high", "medium", "low", "info"],
            "description": "New severity level"
          },
          "state_reason": {
            "type": "string",
            "description": "Reason for the state change (defaults to reason if omitted)"
          },
          "severity_reason": {
            "type": "string",
            "description": "Reason for the severity change (defaults to reason if omitted)"
          },
          "reason": {
            "type": "string",
            "description": "Shorthand reason applied to both state and severity changes when their specific reason is not provided"
          },
          "duplicate_of": {
            "type": "string",
            "nullable": true,
            "description": "UUID of the canonical finding to mark this finding as a duplicate of, or null to unmark. The target must be in the same repository."
          }
        }
      },
      "RestUpdateFindingResponseDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "open",
              "true_positive",
              "false_positive",
              "accepted_risk",
              "resolved",
              "closed"
            ]
          },
          "severity": {
            "type": "string",
            "enum": ["critical", "high", "medium", "low", "info"]
          },
          "duplicate_of": {
            "type": "string",
            "nullable": true,
            "description": "UUID of the canonical finding this duplicates, if any."
          }
        },
        "required": ["id", "state", "severity", "duplicate_of"]
      },
      "RestAddCommentDto": {
        "type": "object",
        "properties": {
          "comment": {
            "type": "string",
            "description": "Comment text",
            "maxLength": 4000
          }
        },
        "required": ["comment"]
      },
      "RestAddCommentResponseDto": {
        "type": "object",
        "properties": {
          "comment_id": {
            "type": "string"
          }
        },
        "required": ["comment_id"]
      },
      "RestStartRemediationResponseDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Run id",
            "format": "uuid"
          },
          "finding_uuid": {
            "type": "string",
            "description": "Finding the run fixes",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": [
              "dispatched",
              "pr_created",
              "no_fix",
              "false_positive",
              "failed",
              "stopped_cap_exceeded",
              "pr_closed",
              "fix_ready"
            ],
            "description": "dispatched while the fix is generated and its pull request opened; pr_created once the pull request is open; fix_ready when the fix was kept without opening a pull request; no_fix, false_positive, failed or stopped_cap_exceeded when it ended without one; pr_closed when the finding was fixed some other way"
          },
          "pr_url": {
            "type": "string",
            "nullable": true,
            "description": "The fix pull request, once it is open"
          },
          "failure_reason": {
            "type": "string",
            "nullable": true,
            "description": "Why the run failed or found no fix"
          },
          "created_at": {
            "type": "string",
            "description": "When the run started"
          },
          "url": {
            "type": "string",
            "description": "The run in Hacktron"
          },
          "started": {
            "type": "boolean",
            "description": "False when the finding's latest run is returned instead of starting another: one in progress, one with an open fix pull request, one whose fix is ready without a pull request, or one that ended without a fix (no_fix, false_positive, stopped_cap_exceeded). A new run starts only when the finding has none or its latest failed or had its pull request closed"
          }
        },
        "required": [
          "id",
          "finding_uuid",
          "status",
          "pr_url",
          "failure_reason",
          "created_at",
          "url",
          "started"
        ]
      },
      "RestRemediationDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Run id",
            "format": "uuid"
          },
          "finding_uuid": {
            "type": "string",
            "description": "Finding the run fixes",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": [
              "dispatched",
              "pr_created",
              "no_fix",
              "false_positive",
              "failed",
              "stopped_cap_exceeded",
              "pr_closed",
              "fix_ready"
            ],
            "description": "dispatched while the fix is generated and its pull request opened; pr_created once the pull request is open; fix_ready when the fix was kept without opening a pull request; no_fix, false_positive, failed or stopped_cap_exceeded when it ended without one; pr_closed when the finding was fixed some other way"
          },
          "pr_url": {
            "type": "string",
            "nullable": true,
            "description": "The fix pull request, once it is open"
          },
          "failure_reason": {
            "type": "string",
            "nullable": true,
            "description": "Why the run failed or found no fix"
          },
          "created_at": {
            "type": "string",
            "description": "When the run started"
          },
          "url": {
            "type": "string",
            "description": "The run in Hacktron"
          }
        },
        "required": [
          "id",
          "finding_uuid",
          "status",
          "pr_url",
          "failure_reason",
          "created_at",
          "url"
        ]
      },
      "RestFindingRemediationDto": {
        "type": "object",
        "properties": {
          "remediation": {
            "nullable": true,
            "description": "The finding's latest run; null when no fix was ever started",
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/RestRemediationDto"
              }
            ]
          }
        },
        "required": ["remediation"]
      },
      "RestTriageThreadEntryDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "reaction": {
            "type": "string",
            "nullable": true
          },
          "comment": {
            "type": "string",
            "nullable": true
          },
          "user_id": {
            "type": "string"
          },
          "username": {
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "timestamp": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "reaction",
          "comment",
          "user_id",
          "source",
          "timestamp"
        ]
      },
      "TaintStepDto": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": ["source", "propagation", "sink"]
          },
          "file": {
            "type": "string"
          },
          "line": {
            "type": "number"
          },
          "end_line": {
            "type": "number"
          },
          "symbol": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "detail": {
            "type": "string",
            "description": "Raw symbol docstring; supplemental context for the stepped taint flow."
          },
          "taint_sources": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "code": {
            "type": "string",
            "description": "Source code lines for this step's symbol, pre-sliced by the worker."
          },
          "code_start_line": {
            "type": "number",
            "description": "1-based start line number of the `code` slice in the source file. Used by the frontend as the anchor for chevron-expand requests to GET /findings/:uuid/source."
          },
          "code_end_line": {
            "type": "number",
            "description": "1-based end line number of the `code` slice in the source file. Used by the frontend as the anchor for chevron-expand requests to GET /findings/:uuid/source."
          }
        },
        "required": [
          "type",
          "file",
          "line",
          "end_line",
          "symbol",
          "description",
          "taint_sources"
        ]
      },
      "RestFindingDetailResponseDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Finding UUID"
          },
          "display_id": {
            "type": "string",
            "description": "Human-readable id (KEY-FD-NUMBER).",
            "example": "HAC-FD-1104"
          },
          "number": {
            "type": "integer",
            "description": "Per-organization sequence number behind display_id.",
            "example": 1104
          },
          "title": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "severity": {
            "type": "string",
            "enum": ["critical", "high", "medium", "low", "info"]
          },
          "state": {
            "type": "string",
            "enum": [
              "open",
              "true_positive",
              "false_positive",
              "accepted_risk",
              "resolved",
              "closed"
            ]
          },
          "description": {
            "type": "string"
          },
          "affected_file": {
            "type": "string"
          },
          "affected_code": {
            "type": "string"
          },
          "proof_of_concept": {
            "type": "string",
            "nullable": true
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "scan_id": {
            "type": "string",
            "nullable": true
          },
          "found_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          },
          "resolved_at": {
            "type": "string",
            "nullable": true,
            "description": "Timestamp of the most recent transition to resolved (ISO 8601). Null if never resolved."
          },
          "triage_thread": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RestTriageThreadEntryDto"
            }
          },
          "taint_path": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TaintStepDto"
            }
          },
          "occurrence_count": {
            "type": "number"
          },
          "repo_url": {
            "type": "string",
            "nullable": true
          },
          "scan_type": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "id",
          "display_id",
          "number",
          "title",
          "category",
          "severity",
          "state",
          "description",
          "affected_file",
          "affected_code",
          "proof_of_concept",
          "tags",
          "scan_id",
          "found_at",
          "updated_at",
          "resolved_at",
          "triage_thread",
          "taint_path",
          "occurrence_count",
          "repo_url",
          "scan_type"
        ]
      },
      "ConnectedCostEstimationRepoDto": {
        "type": "object",
        "properties": {
          "source": {
            "type": "string",
            "description": "Source type",
            "enum": ["connected"],
            "default": "connected"
          },
          "repo_url": {
            "type": "string",
            "description": "Repository URL"
          },
          "branch": {
            "type": "string",
            "description": "Branch name"
          },
          "github_installation_id": {
            "type": "number",
            "description": "GitHub App installation ID. Omitted for PAT-based connections (e.g. GitHub Enterprise), where the installation is resolved from repo_url and the organization instead."
          }
        },
        "required": ["source", "repo_url", "branch"]
      },
      "PublicCostEstimationRepoDto": {
        "type": "object",
        "properties": {
          "source": {
            "type": "string",
            "description": "Source type",
            "enum": ["public"]
          },
          "repo_url": {
            "type": "string",
            "description": "Repository URL"
          },
          "branch": {
            "type": "string",
            "description": "Branch name"
          }
        },
        "required": ["source", "repo_url", "branch"]
      },
      "UploadCostEstimationRepoDto": {
        "type": "object",
        "properties": {
          "source": {
            "type": "string",
            "description": "Source type",
            "enum": ["upload"]
          },
          "archive_id": {
            "type": "string",
            "description": "Scan archive ID"
          }
        },
        "required": ["source", "archive_id"]
      },
      "CreateCostEstimationDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Friendly name for this estimation"
          },
          "repos": {
            "type": "array",
            "description": "Repositories to estimate",
            "items": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/ConnectedCostEstimationRepoDto"
                },
                {
                  "$ref": "#/components/schemas/PublicCostEstimationRepoDto"
                },
                {
                  "$ref": "#/components/schemas/UploadCostEstimationRepoDto"
                }
              ],
              "discriminator": {
                "propertyName": "source",
                "mapping": {
                  "connected": "#/components/schemas/ConnectedCostEstimationRepoDto",
                  "public": "#/components/schemas/PublicCostEstimationRepoDto",
                  "upload": "#/components/schemas/UploadCostEstimationRepoDto"
                }
              }
            }
          }
        },
        "required": ["repos"]
      },
      "RepoInputResponseDto": {
        "type": "object",
        "properties": {
          "source": {
            "type": "string",
            "description": "Source type",
            "enum": ["connected", "public", "upload"]
          },
          "repo_url": {
            "type": "string",
            "description": "Repository URL",
            "example": "https://github.com/owner/repo"
          },
          "branch": {
            "type": "string",
            "description": "Branch name",
            "example": "main"
          },
          "commit_sha": {
            "type": "string",
            "description": "Resolved commit SHA",
            "example": "abc123def456"
          },
          "archive_id": {
            "type": "string",
            "description": "Archive ID (for upload sources)"
          }
        }
      },
      "RepoResultApplicationDto": {
        "type": "object",
        "properties": {
          "app_name": {
            "type": "string",
            "description": "Application name",
            "example": "backend-api"
          },
          "app_root_path": {
            "type": "string",
            "description": "Application root path",
            "example": "apps/api"
          },
          "architecture": {
            "type": "string",
            "description": "Architecture description",
            "example": "NestJS REST API with PostgreSQL"
          }
        },
        "required": ["app_name", "app_root_path"]
      },
      "LocTreeNodeDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Folder name",
            "example": "src"
          },
          "path": {
            "type": "string",
            "description": "Folder path from the repository root; surplus subfolders fold into a row whose path ends in an ellipsis",
            "example": "src/api"
          },
          "loc": {
            "type": "number",
            "description": "Non-blank lines of code in the folder, including subfolders",
            "example": 12040
          },
          "code_bytes": {
            "type": "number",
            "description": "Non-whitespace bytes of code in the folder, including subfolders",
            "example": 350000
          },
          "credits": {
            "type": "number",
            "description": "Credits allocated to the folder; subfolders share them by bytes and the folder's own files keep the rest, so they can add up to less",
            "example": 120
          },
          "children": {
            "description": "Subfolders, largest first",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LocTreeNodeDto"
            }
          }
        },
        "required": ["name", "path", "loc", "children"]
      },
      "RepoResultResponseDto": {
        "type": "object",
        "properties": {
          "repo_url": {
            "type": "string",
            "description": "Repository URL",
            "example": "https://github.com/owner/repo"
          },
          "branch": {
            "type": "string",
            "description": "Branch name",
            "example": "main"
          },
          "commit_sha": {
            "type": "string",
            "description": "Commit SHA",
            "example": "abc123def456"
          },
          "status": {
            "type": "string",
            "description": "Result status",
            "enum": ["completed", "failed"],
            "example": "completed"
          },
          "from_cache": {
            "type": "boolean",
            "description": "Whether result was served from cache",
            "example": false
          },
          "applications": {
            "description": "Detected applications",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RepoResultApplicationDto"
            }
          },
          "credits": {
            "type": "number",
            "description": "Estimated credits for this repo",
            "example": 4000
          },
          "error": {
            "type": "string",
            "description": "Error message (when status is failed)"
          },
          "failure_reason": {
            "type": "string",
            "description": "Structured failure reason",
            "enum": ["unsupported_language", "scope_no_match"]
          },
          "unsupported_languages": {
            "description": "Detected unsupported languages among the top languages",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "scoped_file_count": {
            "type": "number",
            "description": "Files that matched the repository's whitebox scope rules, counted on disk before analysis. Absent for unscoped repositories.",
            "example": 42
          },
          "lines_of_code": {
            "type": "number",
            "description": "Non-blank lines of code in the files the engine indexes",
            "example": 48210
          },
          "code_bytes": {
            "type": "number",
            "description": "Non-whitespace bytes of code used to calculate the quote",
            "example": 1417000
          },
          "loc_tree": {
            "description": "Lines of code and allocated credits per folder",
            "allOf": [
              {
                "$ref": "#/components/schemas/LocTreeNodeDto"
              }
            ]
          }
        },
        "required": ["repo_url", "status", "from_cache"]
      },
      "CostEstimationResponseDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Estimation UUID",
            "example": "123e4567-e89b-12d3-a456-426614174000"
          },
          "organization_id": {
            "type": "string",
            "description": "Organization UUID",
            "example": "f336d0bc-b841-465b-8045-024475c079dd"
          },
          "user_id": {
            "type": "string",
            "description": "User UUID",
            "example": "f336d0bc-b841-465b-8045-024475c079dd"
          },
          "name": {
            "type": "string",
            "description": "Friendly name for this estimation"
          },
          "task_id": {
            "type": "string",
            "description": "Task identifier",
            "example": "cost_est_owner-repo_12345"
          },
          "status": {
            "type": "string",
            "description": "Estimation status",
            "enum": ["pending", "running", "completed", "partial", "failed"],
            "example": "completed"
          },
          "repos": {
            "description": "Input repositories",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RepoInputResponseDto"
            }
          },
          "total_credits": {
            "type": "number",
            "description": "Total estimated credits across all repos",
            "example": 8000
          },
          "repo_results": {
            "description": "Per-repo estimation results",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RepoResultResponseDto"
            }
          },
          "error": {
            "type": "string",
            "description": "Error message"
          },
          "triage_required": {
            "type": "boolean",
            "description": "Whether human triage is mandatory for a scan of this estimation (large app, above the predicted-cost threshold). The customer cannot opt out when true.",
            "example": false
          },
          "triage_fee_credits": {
            "type": "number",
            "description": "Triage fee in credits (a percentage of the scan base credits) added when triage is enabled",
            "example": 1600
          },
          "created_at": {
            "format": "date-time",
            "type": "string",
            "description": "Timestamp when estimation was created",
            "example": "2026-03-10T12:00:00.000Z"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string",
            "description": "Timestamp when estimation was last updated",
            "example": "2026-03-10T12:05:00.000Z"
          }
        },
        "required": [
          "id",
          "organization_id",
          "user_id",
          "task_id",
          "status",
          "repos",
          "triage_required",
          "triage_fee_credits",
          "created_at",
          "updated_at"
        ]
      },
      "RestCostEstimationListResponseDto": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CostEstimationResponseDto"
            }
          },
          "total": {
            "type": "number"
          }
        },
        "required": ["data", "total"]
      },
      "UnifiedRepoDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Internal UUID",
            "example": "123e4567-e89b-12d3-a456-426614174000"
          },
          "provider": {
            "type": "string",
            "description": "Source provider",
            "enum": ["github", "gitlab", "bitbucket", "azure"],
            "example": "github"
          },
          "name": {
            "type": "string",
            "description": "Display name (owner/repo for GitHub, namespace/project for GitLab, workspace/slug for Bitbucket, project/repository for Azure DevOps)",
            "example": "octocat/Hello-World"
          },
          "providerKey": {
            "type": "string",
            "description": "Provider-native identifier for mutation endpoints. GitHub: owner/repo, GitLab: numeric projectId (as string), Bitbucket: repository UUID, Azure DevOps: repository UUID.",
            "example": "octocat/Hello-World"
          },
          "enabled": {
            "type": "boolean",
            "description": "Whether the repository is enabled for scanning",
            "example": true
          },
          "threatModelUpdatedAt": {
            "type": "string",
            "nullable": true,
            "description": "ISO timestamp of the repo's most recent threat_model.md update, or null if it has none. Repos are returned ordered by this (most recent first; repos without a threat model last).",
            "example": "2026-06-22T12:00:00.000Z"
          },
          "openFindingsCount": {
            "type": "number",
            "description": "Number of approved, visible findings that remain open for this repository",
            "example": 3
          },
          "lastScanAt": {
            "type": "string",
            "nullable": true,
            "description": "ISO timestamp of the most recent completed scan containing this repository, or null if it has not been scanned",
            "example": "2026-09-15T12:00:00.000Z"
          },
          "ossApproved": {
            "type": "boolean",
            "description": "Whether this github.com repository is approved for free OSS PR reviews. Independent of whether PR scans are enabled.",
            "example": true
          },
          "prScansEnabled": {
            "type": "boolean",
            "description": "Whether PR/MR scans are enabled (GitHub and GitLab)",
            "example": true
          },
          "prScanBranches": {
            "description": "Target branch patterns for PR/MR scans (GitHub and GitLab)",
            "example": ["main", "**/release/**"],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "installationId": {
            "type": "number",
            "description": "GitHub App installation ID (GitHub only)",
            "example": 12345678
          },
          "baseUrl": {
            "type": "string",
            "nullable": true,
            "description": "GitHub Enterprise base URL for self-hosted (PAT) installations (null/absent for github.com), the GitLab installation URL, or the Azure DevOps organization URL. Clients should build clone/display URLs from this host instead of assuming the public provider host.",
            "example": "https://ghe.example.com"
          },
          "defaultBranch": {
            "type": "string",
            "description": "Default branch (GitLab only)",
            "example": "main"
          },
          "visibility": {
            "type": "string",
            "description": "Project visibility (GitLab only)",
            "example": "private"
          },
          "webhookRegistered": {
            "type": "boolean",
            "description": "Whether a webhook is registered for this project (GitLab only)",
            "example": true
          },
          "isPrivate": {
            "type": "boolean",
            "description": "Whether the repository is private (Bitbucket only)",
            "example": true
          }
        },
        "required": [
          "id",
          "provider",
          "name",
          "providerKey",
          "enabled",
          "threatModelUpdatedAt",
          "openFindingsCount",
          "lastScanAt"
        ]
      },
      "MergedReposResponseDto": {
        "type": "object",
        "properties": {
          "repos": {
            "description": "Unified list of repositories from all providers",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UnifiedRepoDto"
            }
          },
          "errors": {
            "description": "Providers that failed to respond",
            "example": [],
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": ["repos", "errors"]
      },
      "RepositoryIdBatchDto": {
        "type": "object",
        "properties": {
          "enable": {
            "description": "Ids from the repository list of the repositories to turn on",
            "example": ["123e4567-e89b-12d3-a456-426614174000"],
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "disable": {
            "description": "Ids from the repository list of the repositories to turn off",
            "example": [],
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            }
          }
        },
        "required": ["enable", "disable"]
      },
      "RepositoryBatchFailureDto": {
        "type": "object",
        "properties": {
          "repo": {
            "type": "string",
            "description": "The key the request named",
            "example": "acme/api"
          },
          "reason": {
            "type": "string",
            "description": "Why the key was not applied",
            "example": "Repository acme/api not found"
          }
        },
        "required": ["repo", "reason"]
      },
      "RepositoryBatchResultDto": {
        "type": "object",
        "properties": {
          "processed": {
            "type": "number",
            "description": "Keys applied",
            "example": 2
          },
          "failed": {
            "type": "number",
            "description": "Keys that failed",
            "example": 0
          },
          "failedRepositories": {
            "description": "Keys that failed, with the reason",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RepositoryBatchFailureDto"
            }
          },
          "webhookPending": {
            "description": "Keys turned on whose provider webhook could not be registered",
            "example": [],
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "processed",
          "failed",
          "failedRepositories",
          "webhookPending"
        ]
      },
      "RestHfwBatchPackageDto": {
        "type": "object",
        "properties": {
          "ecosystem": {
            "type": "string",
            "enum": ["npm", "pypi"]
          },
          "package": {
            "type": "string"
          },
          "version": {
            "type": "string"
          }
        },
        "required": ["ecosystem", "package", "version"]
      },
      "RestHfwBatchRequestDto": {
        "type": "object",
        "properties": {
          "packages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RestHfwBatchPackageDto"
            }
          }
        },
        "required": ["packages"]
      },
      "RestHfwVerdictResponseDto": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": ["ready", "pending", "scanning"]
          },
          "ecosystem": {
            "type": "string",
            "enum": ["npm", "pypi"]
          },
          "package": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "level": {
            "type": "string",
            "enum": ["clean", "suspicious", "malicious", "unknown"]
          },
          "confidence": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "findings": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "source": {
            "type": "string"
          },
          "osv_id": {
            "type": "string"
          }
        },
        "required": [
          "status",
          "ecosystem",
          "package",
          "version",
          "level",
          "confidence",
          "summary",
          "findings"
        ]
      },
      "RestHfwBatchResponseDto": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "verdicts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RestHfwVerdictResponseDto"
            }
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        },
        "required": ["status", "verdicts", "errors"]
      },
      "RestHfwOsvFeedResultDto": {
        "type": "object",
        "properties": {
          "ecosystem": {
            "type": "string"
          },
          "package": {
            "type": "string"
          },
          "versions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": ["ecosystem", "package", "versions"]
      },
      "RestHfwOsvFeedResponseDto": {
        "type": "object",
        "properties": {
          "total": {
            "type": "number"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RestHfwOsvFeedResultDto"
            }
          }
        },
        "required": ["results"]
      },
      "ConnectedRepoInputDto": {
        "type": "object",
        "properties": {
          "include_paths": {
            "description": "Whitebox scope: gitignore-style globs (relative to the repo root) that narrow the scan to matching paths. Empty means the whole repository.",
            "example": ["services/gateway/**"],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "exclude_paths": {
            "description": "Whitebox scope: gitignore-style globs removed from the scan after include_paths is applied; use `*.md` to drop a file type.",
            "example": ["**/tests/**", "vendor/", "*.md"],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "source": {
            "type": "string",
            "enum": ["connected"]
          },
          "url": {
            "type": "string",
            "description": "Repository URL",
            "example": "https://github.com/owner/repo"
          },
          "branch": {
            "type": "string",
            "description": "Branch name, tag name, or commit SHA"
          },
          "ref_type": {
            "type": "string",
            "enum": ["branch", "tag", "sha"],
            "description": "How `branch` was selected (UI hint for draft re-use)"
          },
          "github_installation_id": {
            "type": "number",
            "description": "GitHub App installation id. Omitted for PAT-based connections (e.g. GitHub Enterprise), where the installation is resolved from the repository URL and the organization instead."
          }
        },
        "required": ["source", "url", "branch"]
      },
      "PublicRepoInputDto": {
        "type": "object",
        "properties": {
          "include_paths": {
            "description": "Whitebox scope: gitignore-style globs (relative to the repo root) that narrow the scan to matching paths. Empty means the whole repository.",
            "example": ["services/gateway/**"],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "exclude_paths": {
            "description": "Whitebox scope: gitignore-style globs removed from the scan after include_paths is applied; use `*.md` to drop a file type.",
            "example": ["**/tests/**", "vendor/", "*.md"],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "source": {
            "type": "string",
            "enum": ["public"]
          },
          "url": {
            "type": "string",
            "description": "Repository URL",
            "example": "https://github.com/owner/repo"
          },
          "branch": {
            "type": "string",
            "description": "Branch name, tag name, or commit SHA"
          },
          "ref_type": {
            "type": "string",
            "enum": ["branch", "tag", "sha"],
            "description": "How `branch` was selected (UI hint for draft re-use)"
          }
        },
        "required": ["source", "url", "branch"]
      },
      "UploadRepoInputDto": {
        "type": "object",
        "properties": {
          "include_paths": {
            "description": "Whitebox scope: gitignore-style globs (relative to the repo root) that narrow the scan to matching paths. Empty means the whole repository.",
            "example": ["services/gateway/**"],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "exclude_paths": {
            "description": "Whitebox scope: gitignore-style globs removed from the scan after include_paths is applied; use `*.md` to drop a file type.",
            "example": ["**/tests/**", "vendor/", "*.md"],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "source": {
            "type": "string",
            "enum": ["upload"]
          },
          "archive_id": {
            "type": "string",
            "description": "Scan archive ID"
          }
        },
        "required": ["source", "archive_id"]
      },
      "RestLoginTargetDto": {
        "type": "object",
        "properties": {
          "site": {
            "type": "string",
            "description": "A deployed copy of the app to test signed in, e.g. https://staging.acme.dev",
            "maxLength": 2048
          },
          "login_instructions": {
            "type": "string",
            "description": "How to sign in: the login page, username, password and any steps. Stored encrypted and never returned.",
            "maxLength": 2000
          }
        },
        "required": ["site", "login_instructions"]
      },
      "RestCreatePentestDto": {
        "type": "object",
        "properties": {
          "target_urls": {
            "description": "Target URLs (pentest only)",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "custom_context": {
            "type": "string",
            "description": "Custom context (pentest only)"
          },
          "application_id": {
            "type": "string",
            "description": "iva application this scan targets (group of repos)"
          },
          "login_targets": {
            "description": "Deployed sites to test signed in, each with how to sign in. On update the list replaces the saved one, and [] removes them. A pentest tests live sites either all signed in or all without a login (target_urls). Check each login with POST /pentests/{id}/login-checks before starting.",
            "maxItems": 10,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RestLoginTargetDto"
            }
          },
          "repos": {
            "type": "array",
            "description": "Repositories or uploaded archives to test",
            "items": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/ConnectedRepoInputDto"
                },
                {
                  "$ref": "#/components/schemas/PublicRepoInputDto"
                },
                {
                  "$ref": "#/components/schemas/UploadRepoInputDto"
                }
              ],
              "discriminator": {
                "propertyName": "source",
                "mapping": {
                  "connected": "#/components/schemas/ConnectedRepoInputDto",
                  "public": "#/components/schemas/PublicRepoInputDto",
                  "upload": "#/components/schemas/UploadRepoInputDto"
                }
              }
            },
            "minItems": 1
          }
        },
        "required": ["repos"]
      },
      "RepoDataDto": {
        "type": "object",
        "properties": {
          "include_paths": {
            "description": "Whitebox scope: gitignore-style globs (relative to the repo root) that narrow the scan to matching paths. Empty means the whole repository.",
            "example": ["services/gateway/**"],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "exclude_paths": {
            "description": "Whitebox scope: gitignore-style globs removed from the scan after include_paths is applied; use `*.md` to drop a file type.",
            "example": ["**/tests/**", "vendor/", "*.md"],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "source": {
            "type": "string",
            "enum": ["connected", "public", "upload"]
          },
          "provider": {
            "type": "string",
            "enum": ["github", "gitlab", "bitbucket", "azure"],
            "readOnly": true,
            "description": "Resolved by the server at scan start; ignored on input"
          },
          "url": {
            "type": "string",
            "description": "Repository URL",
            "example": "https://github.com/owner/repo"
          },
          "branch": {
            "type": "string",
            "description": "Branch name, tag name, or commit SHA"
          },
          "ref_type": {
            "type": "string",
            "enum": ["branch", "tag", "sha"],
            "description": "How `branch` was selected (UI hint for draft re-use)"
          },
          "archive_id": {
            "type": "string",
            "description": "Scan archive ID"
          },
          "github_installation_id": {
            "type": "number",
            "description": "GitHub App installation ID (connected repos only)"
          }
        }
      },
      "RestPentestLoginTargetDto": {
        "type": "object",
        "properties": {
          "site": {
            "type": "string"
          },
          "login_check": {
            "type": "string",
            "enum": [
              "unverified",
              "pending",
              "running",
              "succeeded",
              "failed",
              "cancelled",
              "expired"
            ],
            "description": "Whether Hacktron could sign in with the login the site has now. A pass lasts an hour, and changing the site or login makes it unverified."
          },
          "failure_reason": {
            "type": "string",
            "nullable": true,
            "description": "Why the check failed, without credentials"
          }
        },
        "required": ["site", "login_check", "failure_reason"]
      },
      "RestPentestResponseDto": {
        "type": "object",
        "properties": {
          "scan_id": {
            "type": "string",
            "format": "uuid",
            "description": "Stable pentest id; task_id changes when it starts"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "running",
              "completed",
              "failed",
              "stopped",
              "cancelled",
              "skipped",
              "pending_verification",
              "pending_triage",
              "draft",
              "estimating",
              "estimated"
            ]
          },
          "repos": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RepoDataDto"
            }
          },
          "target_urls": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "login_targets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RestPentestLoginTargetDto"
            }
          },
          "custom_context": {
            "type": "string",
            "nullable": true
          },
          "application_id": {
            "type": "string",
            "nullable": true,
            "format": "uuid"
          },
          "cost_estimation_id": {
            "type": "string",
            "nullable": true,
            "format": "uuid"
          },
          "triage_enabled": {
            "type": "boolean",
            "nullable": true
          },
          "credits_used": {
            "type": "number",
            "nullable": true
          }
        },
        "required": [
          "scan_id",
          "status",
          "repos",
          "target_urls",
          "login_targets",
          "custom_context",
          "application_id",
          "cost_estimation_id",
          "triage_enabled",
          "credits_used"
        ]
      },
      "RestUpdatePentestDto": {
        "type": "object",
        "properties": {
          "target_urls": {
            "description": "Target URLs (pentest only)",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "custom_context": {
            "type": "string",
            "description": "Custom context (pentest only)"
          },
          "application_id": {
            "type": "string",
            "description": "iva application this scan targets (group of repos)"
          },
          "login_targets": {
            "description": "Deployed sites to test signed in, each with how to sign in. On update the list replaces the saved one, and [] removes them. A pentest tests live sites either all signed in or all without a login (target_urls). Check each login with POST /pentests/{id}/login-checks before starting.",
            "maxItems": 10,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RestLoginTargetDto"
            }
          },
          "repos": {
            "type": "array",
            "description": "Repositories or uploaded archives to test, replacing the saved ones. Changing them clears the estimate, so estimate again before starting.",
            "items": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/ConnectedRepoInputDto"
                },
                {
                  "$ref": "#/components/schemas/PublicRepoInputDto"
                },
                {
                  "$ref": "#/components/schemas/UploadRepoInputDto"
                }
              ],
              "discriminator": {
                "propertyName": "source",
                "mapping": {
                  "connected": "#/components/schemas/ConnectedRepoInputDto",
                  "public": "#/components/schemas/PublicRepoInputDto",
                  "upload": "#/components/schemas/UploadRepoInputDto"
                }
              }
            },
            "minItems": 1
          }
        }
      },
      "RestStartPentestDto": {
        "type": "object",
        "properties": {
          "expected_credits": {
            "type": "integer",
            "description": "The total the user confirmed: the estimate's total_credits, plus triage_fee_credits when triage is required or opted in",
            "minimum": 1
          },
          "triage_enabled": {
            "type": "boolean",
            "description": "Opt in to human triage of findings when it is not already required"
          }
        },
        "required": ["expected_credits"]
      },
      "RestDiscardPentestResponseDto": {
        "type": "object",
        "properties": {
          "scan_id": {
            "type": "string",
            "format": "uuid"
          },
          "discarded": {
            "type": "boolean"
          }
        },
        "required": ["scan_id", "discarded"]
      },
      "RequestUploadDto": {
        "type": "object",
        "properties": {
          "file_name": {
            "type": "string",
            "description": "Original filename (e.g. \"my-project.zip\")",
            "example": "my-project.zip"
          },
          "name": {
            "type": "string",
            "description": "Display name (defaults to filename)"
          }
        },
        "required": ["file_name"]
      },
      "RequestUploadResponseDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Archive ID"
          },
          "upload_url": {
            "type": "string",
            "description": "Signed GCS upload URL (PUT)"
          },
          "content_type": {
            "type": "string",
            "description": "Content-Type to use in the PUT request",
            "example": "application/zip"
          }
        },
        "required": ["id", "upload_url", "content_type"]
      },
      "PentestCreditBalanceResponseDto": {
        "type": "object",
        "properties": {
          "organization_id": {
            "type": "string",
            "description": "Organization UUID",
            "example": "f336d0bc-b841-465b-8045-024475c079dd"
          },
          "balance": {
            "type": "number",
            "description": "Current pentest credit balance available for use",
            "example": 12000
          },
          "total_purchased": {
            "type": "number",
            "description": "Total pentest credits purchased across all time",
            "example": 16000
          },
          "total_used": {
            "type": "number",
            "description": "Total pentest credits deducted for completed/running pentests",
            "example": 8000
          },
          "total_refunded": {
            "type": "number",
            "description": "Total pentest credits refunded from cancelled pentests",
            "example": 4000
          },
          "total_granted": {
            "type": "number",
            "description": "Total pentest credits granted at no charge",
            "example": 2000
          },
          "used_this_period": {
            "type": "number",
            "nullable": true,
            "description": "Credits deducted since the start of the current billing period, null when the organization has no billing period",
            "example": 1240
          },
          "is_unlimited": {
            "type": "boolean",
            "description": "Whether this organization has internal unlimited pentest entitlement",
            "example": false
          }
        },
        "required": [
          "organization_id",
          "balance",
          "total_purchased",
          "total_used",
          "total_refunded",
          "total_granted",
          "used_this_period",
          "is_unlimited"
        ]
      },
      "AutomationCreditBalanceResponseDto": {
        "type": "object",
        "properties": {
          "organization_id": {
            "type": "string",
            "description": "Organization UUID",
            "example": "f336d0bc-b841-465b-8045-024475c079dd"
          },
          "balance": {
            "type": "number",
            "description": "Current automation credit balance (may be negative)",
            "example": 4150
          },
          "total_purchased": {
            "type": "number",
            "description": "Total automation credits purchased across all time",
            "example": 8000
          },
          "total_used": {
            "type": "number",
            "description": "Total automation credits deducted for completed runs",
            "example": 3850
          },
          "total_granted": {
            "type": "number",
            "description": "Total automation credits granted",
            "example": 2000
          },
          "used_this_period": {
            "type": "number",
            "nullable": true,
            "description": "Credits deducted since the start of the current billing period, null when the organization has no billing period",
            "example": 1240
          },
          "is_unlimited": {
            "type": "boolean",
            "description": "Whether this organization has internal unlimited entitlement (runs are never charged)",
            "example": false
          }
        },
        "required": [
          "organization_id",
          "balance",
          "total_purchased",
          "total_used",
          "total_granted",
          "used_this_period",
          "is_unlimited"
        ]
      },
      "RestPrReviewSettingsDto": {
        "type": "object",
        "properties": {
          "scm_comments_enabled": {
            "type": "boolean",
            "description": "Whether Hacktron publishes comments and finding details to connected source control pull and merge requests"
          },
          "scm_system_comments_enabled": {
            "type": "boolean",
            "description": "Whether Hacktron posts system comments such as skipped reviews, usage limits, and configuration warnings. Defaults to true. Requires scm_comments_enabled."
          },
          "scm_check_statuses_enabled": {
            "type": "boolean",
            "description": "Whether Hacktron creates and updates check statuses in connected source control providers. Independent of comments. Defaults to true."
          },
          "fail_on_severity": {
            "type": "string",
            "description": "Org-wide default fail_on severity threshold for PR/MR checks. A repo's .hacktron/config.yaml fail_on.severity overrides this. Send null to disable.",
            "enum": ["critical", "high", "medium", "low", "info"],
            "nullable": true
          },
          "scan_include_branches": {
            "description": "Org-wide default target branch patterns to scan PRs/MRs for (null = all branches). Glob patterns (`*`, `**`, `?`, `{a,b}`), case-insensitive. A repo's .hacktron/config.yaml include.branches overrides this.",
            "example": ["main", "**/release/**"],
            "nullable": true,
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "scan_exclude_branches": {
            "description": "Org-wide default target branch patterns to exclude from PR/MR scans (null = none). Takes precedence over scan_include_branches. A repo's .hacktron/config.yaml exclude.branches overrides this.",
            "example": ["**/release/legacy/**"],
            "nullable": true,
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "scan_include_labels": {
            "description": "Org-wide default labels to require on PRs/MRs for scanning (null = any). A repo's .hacktron/config.yaml include.labels overrides this.",
            "example": ["feature", "bugfix"],
            "nullable": true,
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "scan_exclude_labels": {
            "description": "Org-wide default labels to exclude PR/MR scans for (null = none). Takes precedence over scan_include_labels. A repo's .hacktron/config.yaml exclude.labels overrides this.",
            "example": ["wip", "no-scan"],
            "nullable": true,
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "scan_include_authors": {
            "description": "Org-wide default author patterns to require on PRs/MRs for scanning (null = any). Glob patterns (`*`, `**`, `?`, `{a,b}`), case-insensitive. A repo's .hacktron/config.yaml include.authors overrides this.",
            "example": ["alice", "bob"],
            "nullable": true,
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "scan_exclude_authors": {
            "description": "Org-wide default author patterns to exclude PR/MR scans for (null = none). Glob patterns (`*`, `**`, `?`, `{a,b}`), case-insensitive. Takes precedence over scan_include_authors. A repo's .hacktron/config.yaml exclude.authors overrides this.",
            "example": ["dependabot[bot]", "renovate[bot]", "*-bot"],
            "nullable": true,
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "scan_include_keywords": {
            "description": "Org-wide default title keywords to require on PRs/MRs for scanning (null = any). Case-insensitive substring match. A repo's .hacktron/config.yaml include.keywords overrides this.",
            "example": ["release", "security"],
            "nullable": true,
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "scan_exclude_keywords": {
            "description": "Org-wide default title keywords to exclude PR/MR scans for (null = none). Case-insensitive substring match. A repo's .hacktron/config.yaml exclude.keywords overrides this.",
            "example": ["[exclude hacktron]", "wip"],
            "nullable": true,
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "ScmProvider": {
        "type": "string",
        "enum": ["github", "gitlab", "bitbucket", "azure"]
      },
      "RestPullRequestDto": {
        "type": "object",
        "properties": {
          "repository_id": {
            "type": "string",
            "description": "Id from the repository list",
            "format": "uuid"
          },
          "repository": {
            "type": "string",
            "description": "Repository full name",
            "example": "acme/api"
          },
          "provider": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ScmProvider"
              }
            ]
          },
          "number": {
            "type": "number",
            "example": 42
          },
          "title": {
            "type": "string",
            "example": "Add OAuth login"
          },
          "url": {
            "type": "string",
            "description": "Web link to the pull request",
            "example": "https://github.com/acme/api/pull/42"
          },
          "author": {
            "type": "string",
            "nullable": true,
            "description": "The author's name on the provider"
          },
          "is_yours": {
            "type": "boolean",
            "description": "Whether the caller opened it, matched through their linked source control accounts"
          },
          "draft": {
            "type": "boolean"
          },
          "source_branch": {
            "type": "string",
            "example": "feature/oauth"
          },
          "target_branch": {
            "type": "string",
            "example": "main"
          },
          "updated_at": {
            "type": "string",
            "nullable": true,
            "description": "Last update, or creation where the provider reports no update time"
          }
        },
        "required": [
          "repository_id",
          "repository",
          "provider",
          "number",
          "title",
          "url",
          "author",
          "is_yours",
          "draft",
          "source_branch",
          "target_branch",
          "updated_at"
        ]
      },
      "RestPullRequestListDto": {
        "type": "object",
        "properties": {
          "data": {
            "description": "Open pull requests, most recently updated first",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RestPullRequestDto"
            }
          },
          "errors": {
            "description": "Repositories, or whole providers, whose pull requests could not be read; when not empty the list may be incomplete. Repositories Hacktron can't review, such as GitHub ones connected with a personal access token, are left out without an entry",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "truncated": {
            "type": "boolean",
            "description": "True when the organization has more enabled repositories than one listing searches; pass repository_id to list a specific one"
          }
        },
        "required": ["data", "errors", "truncated"]
      },
      "PullRequestState": {
        "type": "string",
        "enum": ["open", "closed", "merged"]
      },
      "PullRequestReviewStatus": {
        "type": "string",
        "enum": ["in_progress", "completed"]
      },
      "RestPullRequestReviewDto": {
        "type": "object",
        "properties": {
          "scan_id": {
            "type": "string",
            "nullable": true,
            "format": "uuid",
            "description": "Scan id, for the scans routes"
          },
          "task_id": {
            "type": "string"
          },
          "status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PullRequestReviewStatus"
              }
            ]
          }
        },
        "required": ["scan_id", "task_id", "status"]
      },
      "RestPullRequestDetailsDto": {
        "type": "object",
        "properties": {
          "repository_id": {
            "type": "string",
            "description": "Id from the repository list",
            "format": "uuid"
          },
          "repository": {
            "type": "string",
            "description": "Repository full name",
            "example": "acme/api"
          },
          "provider": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ScmProvider"
              }
            ]
          },
          "number": {
            "type": "number",
            "example": 42
          },
          "title": {
            "type": "string",
            "example": "Add OAuth login"
          },
          "url": {
            "type": "string",
            "description": "Web link to the pull request",
            "example": "https://github.com/acme/api/pull/42"
          },
          "author": {
            "type": "string",
            "nullable": true,
            "description": "The author's name on the provider"
          },
          "is_yours": {
            "type": "boolean",
            "description": "Whether the caller opened it, matched through their linked source control accounts"
          },
          "draft": {
            "type": "boolean"
          },
          "source_branch": {
            "type": "string",
            "example": "feature/oauth"
          },
          "target_branch": {
            "type": "string",
            "example": "main"
          },
          "updated_at": {
            "type": "string",
            "nullable": true,
            "description": "Last update, or creation where the provider reports no update time"
          },
          "state": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PullRequestState"
              }
            ]
          },
          "head_sha": {
            "type": "string",
            "nullable": true,
            "description": "The commit at the head of the pull request; null when the provider reports none, such as a closed pull request whose fork is gone"
          },
          "review": {
            "nullable": true,
            "description": "Hacktron's review of the head commit, running or finished; null when it has none",
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/RestPullRequestReviewDto"
              }
            ]
          }
        },
        "required": [
          "repository_id",
          "repository",
          "provider",
          "number",
          "title",
          "url",
          "author",
          "is_yours",
          "draft",
          "source_branch",
          "target_branch",
          "updated_at",
          "state",
          "head_sha",
          "review"
        ]
      },
      "RestStartPrReviewDto": {
        "type": "object",
        "properties": {
          "pr_url": {
            "type": "string",
            "description": "The pull or merge request's web link",
            "example": "https://github.com/acme/api/pull/42"
          }
        },
        "required": ["pr_url"]
      },
      "StartPrReviewStatus": {
        "type": "string",
        "enum": ["started", "in_progress", "already_reviewed"],
        "description": "started, or in_progress / already_reviewed when a review of the head commit already exists"
      },
      "RestStartPrReviewResponseDto": {
        "type": "object",
        "properties": {
          "status": {
            "description": "started, or in_progress / already_reviewed when a review of the head commit already exists",
            "allOf": [
              {
                "$ref": "#/components/schemas/StartPrReviewStatus"
              }
            ]
          },
          "scan_id": {
            "type": "string",
            "nullable": true,
            "format": "uuid",
            "description": "Scan id, for the scans routes"
          },
          "task_id": {
            "type": "string"
          },
          "repository": {
            "type": "string",
            "example": "acme/api"
          },
          "number": {
            "type": "number",
            "example": 42
          },
          "url": {
            "type": "string",
            "example": "https://github.com/acme/api/pull/42"
          },
          "posts_comments": {
            "type": "boolean",
            "description": "Whether findings are posted as comments on the pull request (the organization's scm_comments_enabled)"
          },
          "posts_check_status": {
            "type": "boolean",
            "description": "Whether the review shows as a check or status on the pull request (scm_check_statuses_enabled)"
          }
        },
        "required": [
          "status",
          "scan_id",
          "task_id",
          "repository",
          "number",
          "url",
          "posts_comments",
          "posts_check_status"
        ]
      },
      "RestOpenCodeWorkspaceDto": {
        "type": "object",
        "properties": {
          "repository_id": {
            "type": "string",
            "description": "Id from the repository list. Give this, or pull_request_url.",
            "format": "uuid"
          },
          "pull_request_url": {
            "type": "string",
            "description": "A pull or merge request's web link: the workspace opens at its head commit and can diff against its base",
            "example": "https://github.com/acme/api/pull/42"
          },
          "ref": {
            "type": "string",
            "description": "Branch, tag or commit to open with repository_id; the default branch when left out",
            "example": "main"
          }
        }
      },
      "CodeWorkspaceState": {
        "type": "string",
        "enum": ["preparing", "ready", "failed", "closed"],
        "description": "preparing while the code is checked out; queries wait for it"
      },
      "RestCodeWorkspaceDto": {
        "type": "object",
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "Pass to the code query endpoint"
          },
          "repository_id": {
            "type": "string",
            "format": "uuid"
          },
          "repository": {
            "type": "string",
            "example": "acme/api"
          },
          "commit_sha": {
            "type": "string",
            "description": "The commit the workspace reads"
          },
          "base_commit_sha": {
            "type": "string",
            "nullable": true,
            "description": "The pull request's base commit, which diff compares against; null outside a pull request"
          },
          "pull_request_number": {
            "type": "number",
            "nullable": true
          },
          "state": {
            "description": "preparing while the code is checked out; queries wait for it",
            "allOf": [
              {
                "$ref": "#/components/schemas/CodeWorkspaceState"
              }
            ]
          },
          "error": {
            "type": "string",
            "nullable": true,
            "description": "Why the workspace failed"
          }
        },
        "required": [
          "workspace_id",
          "repository_id",
          "repository",
          "commit_sha",
          "base_commit_sha",
          "pull_request_number",
          "state",
          "error"
        ]
      },
      "CodeWorkspaceTool": {
        "type": "string",
        "enum": [
          "run_command",
          "search",
          "read",
          "list",
          "diff",
          "log",
          "blame",
          "dependencies"
        ],
        "description": "run_command (a bash command line in the repository root: rg, sed, git log, git diff, git blame and the like, with no credential and no network), or one of the fixed commands: search (git grep -E), read (a file's lines), list (a directory, or files by name), diff (a pull request against its base), log (commits touching a path), blame (who last changed a file's lines), dependencies (the dependency manifests and lock files, or the lines in them naming a package)"
      },
      "RestCodeQueryDto": {
        "type": "object",
        "properties": {
          "tool": {
            "description": "run_command (a bash command line in the repository root: rg, sed, git log, git diff, git blame and the like, with no credential and no network), or one of the fixed commands: search (git grep -E), read (a file's lines), list (a directory, or files by name), diff (a pull request against its base), log (commits touching a path), blame (who last changed a file's lines), dependencies (the dependency manifests and lock files, or the lines in them naming a package)",
            "allOf": [
              {
                "$ref": "#/components/schemas/CodeWorkspaceTool"
              }
            ]
          },
          "command": {
            "type": "string",
            "description": "For run_command: the bash command line, run from the repository root with a 120s limit; output is cut at 500 lines",
            "example": "rg -n \"jwt\\.verify|verifyToken\" src"
          },
          "path": {
            "type": "string",
            "description": "A path relative to the repository root",
            "example": "src/auth"
          },
          "pattern": {
            "type": "string",
            "description": "Extended regular expression for search; for dependencies, the package name as text",
            "example": "jwt\\.verify|verifyToken"
          },
          "ignore_case": {
            "type": "boolean",
            "default": false
          },
          "context_lines": {
            "type": "number",
            "minimum": 0,
            "maximum": 5,
            "default": 0,
            "description": "Lines of context around each search match"
          },
          "name_pattern": {
            "type": "string",
            "description": "For list: only paths under path matching this extended regular expression, case-insensitive",
            "example": "auth|session"
          },
          "start_line": {
            "type": "number",
            "minimum": 1,
            "default": 1
          },
          "end_line": {
            "type": "number",
            "minimum": 1,
            "description": "Up to 400 lines are read or blamed"
          },
          "recursive": {
            "type": "boolean",
            "default": false,
            "description": "list every file under the path instead of one level"
          }
        },
        "required": ["tool"]
      },
      "RestCodeQueryResultDto": {
        "type": "object",
        "properties": {
          "output": {
            "type": "string",
            "description": "The command's output: for run_command, stdout and stderr together, ending with the exit code when it isn't 0; file:line:text for search, numbered lines for read, paths (directories end in /) for list, commit, author, date and text per line for blame"
          },
          "truncated": {
            "type": "boolean",
            "description": "Whether the output was cut at its limit; narrow the command, path or pattern"
          }
        },
        "required": ["output", "truncated"]
      },
      "ContextDocumentKind": {
        "type": "string",
        "enum": ["threat_model", "application_threat_model", "document"]
      },
      "RestContextDocumentDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "kind": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ContextDocumentKind"
              }
            ]
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "readable": {
            "type": "boolean",
            "description": "Whether the content is text this API returns; PDFs open in Hacktron"
          }
        },
        "required": ["id", "name", "kind", "updated_at", "readable"]
      },
      "RestContextDocumentListDto": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RestContextDocumentDto"
            }
          }
        },
        "required": ["data"]
      },
      "RestContextDocumentContentDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "kind": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ContextDocumentKind"
              }
            ]
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "readable": {
            "type": "boolean",
            "description": "Whether the content is text this API returns; PDFs open in Hacktron"
          },
          "content": {
            "type": "string",
            "description": "Markdown or text content"
          },
          "truncated": {
            "type": "boolean",
            "description": "Whether the content was cut at its limit"
          }
        },
        "required": [
          "id",
          "name",
          "kind",
          "updated_at",
          "readable",
          "content",
          "truncated"
        ]
      },
      "RestAddContextDocumentDto": {
        "type": "object",
        "properties": {
          "repository_id": {
            "type": "string",
            "description": "Id from the repository list",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "Document title",
            "example": "Link previews: security decisions"
          },
          "content": {
            "type": "string",
            "description": "Markdown content"
          }
        },
        "required": ["repository_id", "name", "content"]
      },
      "RestDocumentEditDto": {
        "type": "object",
        "properties": {
          "old_text": {
            "type": "string",
            "description": "Text to replace; it must appear exactly once in the document"
          },
          "new_text": {
            "type": "string",
            "description": "Replacement text; empty deletes old_text"
          }
        },
        "required": ["old_text", "new_text"]
      },
      "RestEditContextDocumentDto": {
        "type": "object",
        "properties": {
          "edits": {
            "description": "Replacements, applied in order",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RestDocumentEditDto"
            }
          },
          "append": {
            "type": "string",
            "description": "Markdown to add at the end of the document"
          }
        }
      },
      "RestThreatModelUpdateDto": {
        "type": "object",
        "properties": {
          "started": {
            "type": "boolean",
            "description": "Whether an update started; false when nothing new was waiting to be folded in"
          },
          "initial": {
            "type": "boolean",
            "description": "Whether this builds the repository's first threat model from its code"
          }
        },
        "required": ["started", "initial"]
      },
      "ApplicationRepoResponseDto": {
        "type": "object",
        "properties": {
          "application_id": {
            "type": "string"
          },
          "repo_url": {
            "type": "string"
          },
          "added_by": {
            "type": "string",
            "nullable": true
          },
          "added_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": ["application_id", "repo_url", "added_by", "added_at"]
      },
      "ApplicationResponseDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "organization_id": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "created_by": {
            "type": "string",
            "nullable": true
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          },
          "repos": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApplicationRepoResponseDto"
            }
          },
          "repo_count": {
            "type": "number"
          },
          "finding_count": {
            "type": "number"
          },
          "threat_model_updated_at": {
            "type": "string",
            "nullable": true,
            "description": "ISO timestamp of the most recently updated threat_model.md across the application's repos, or null if none have one. The list endpoint orders applications by this (most recent first; applications without a threat model last)."
          }
        },
        "required": [
          "id",
          "organization_id",
          "slug",
          "name",
          "tags",
          "created_by",
          "created_at",
          "updated_at"
        ]
      },
      "ApplicationListResponseDto": {
        "type": "object",
        "properties": {
          "applications": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApplicationResponseDto"
            }
          },
          "total": {
            "type": "number"
          }
        },
        "required": ["applications", "total"]
      },
      "RestCreateApplicationDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 128,
            "example": "Payments"
          },
          "repository_ids": {
            "description": "Ids from the repository list",
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": ["name", "repository_ids"]
      },
      "RestApplicationRepositoriesDto": {
        "type": "object",
        "properties": {
          "repository_ids": {
            "description": "Ids from the repository list",
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": ["repository_ids"]
      },
      "ApplicationRepoListResponseDto": {
        "type": "object",
        "properties": {
          "repos": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApplicationRepoResponseDto"
            }
          }
        },
        "required": ["repos"]
      },
      "ThreatModelSyncResponseDto": {
        "type": "object",
        "properties": {
          "started": {
            "type": "boolean",
            "description": "True if a workflow was started; false if nothing was pending."
          }
        },
        "required": ["started"]
      },
      "KeyFindingDetailDto": {
        "type": "object",
        "properties": {
          "findingId": {
            "type": "string",
            "description": "Stable label like F-001 (severity-sorted index)."
          },
          "uuid": {
            "type": "string",
            "description": "findings.uuid for cross-reference to detailed report."
          },
          "title": {
            "type": "string"
          },
          "severity": {
            "type": "string",
            "enum": ["critical", "high", "medium", "low", "info"]
          }
        },
        "required": ["findingId", "uuid", "title", "severity"]
      },
      "ExecSummaryResponseDto": {
        "type": "object",
        "properties": {
          "narrativeMarkdown": {
            "type": "string",
            "description": "LLM-generated narrative in markdown."
          },
          "severityCounts": {
            "type": "object",
            "description": "Severity counts as reported by the model.",
            "additionalProperties": {
              "type": "integer"
            },
            "example": {
              "critical": 1,
              "high": 3,
              "medium": 5,
              "low": 2,
              "info": 0
            }
          },
          "keyFindingsDetail": {
            "description": "All findings, severity-sorted with stable F-001 labels (severity rank, then UUID tiebreak).",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/KeyFindingDetailDto"
            }
          },
          "riskRating": {
            "type": "string",
            "description": "Deterministic risk rating computed from severity mix.",
            "enum": ["CRITICAL", "HIGH", "MEDIUM", "LOW"]
          },
          "riskRationale": {
            "type": "string",
            "description": "LLM-generated rationale for the risk rating."
          },
          "conclusion": {
            "type": "string",
            "description": "LLM-generated closing paragraph."
          },
          "nextSteps": {
            "type": "string",
            "description": "LLM-generated next steps as a markdown numbered list."
          },
          "generatedAt": {
            "type": "string",
            "description": "ISO timestamp of last generation."
          },
          "isStale": {
            "type": "boolean",
            "description": "True if findings have changed since this narrative was generated."
          },
          "model": {
            "type": "string",
            "description": "Model identifier used for generation."
          }
        },
        "required": [
          "narrativeMarkdown",
          "severityCounts",
          "keyFindingsDetail",
          "riskRating",
          "riskRationale",
          "conclusion",
          "nextSteps",
          "generatedAt",
          "isStale",
          "model"
        ]
      },
      "CoveragePassDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Trace-scan pass id, e.g. authz."
          },
          "name": {
            "type": "string",
            "description": "Display name of the pass."
          }
        },
        "required": ["id", "name"]
      },
      "CoveragePassCountDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Trace-scan pass id."
          },
          "analysed": {
            "type": "number",
            "description": "Functions this pass analysed."
          }
        },
        "required": ["id", "analysed"]
      },
      "CoverageSurfaceDto": {
        "type": "object",
        "properties": {
          "tag": {
            "type": "string",
            "description": "Enrichment tag, e.g. authentication."
          },
          "symbols": {
            "type": "number",
            "description": "Functions carrying the tag."
          },
          "analysed": {
            "type": "number",
            "description": "Functions with the tag analysed by any pass."
          },
          "passes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CoveragePassCountDto"
            }
          },
          "examples": {
            "description": "Names of up to five analysed functions with the tag: the ones the summary cites, or else entry points first.",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "summary": {
            "type": "string",
            "nullable": true,
            "description": "Model-written feature summary, kept only when it cites functions from this area."
          }
        },
        "required": ["tag", "symbols", "analysed", "passes", "examples"]
      },
      "CoverageEntrypointDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "filePath": {
            "type": "string"
          },
          "line": {
            "type": "number"
          },
          "taintSources": {
            "description": "Untrusted input types, e.g. http_input.",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "passes": {
            "description": "Ids of the passes that analysed it.",
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "name",
          "description",
          "filePath",
          "line",
          "taintSources",
          "passes"
        ]
      },
      "ApplicationCoverageDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "rootPath": {
            "type": "string"
          },
          "symbols": {
            "type": "number",
            "description": "Functions in the application."
          },
          "analysed": {
            "type": "number",
            "description": "Functions analysed by any pass."
          },
          "previouslyAnalysed": {
            "type": "number",
            "description": "Functions only an earlier scan of this repository analysed."
          },
          "passes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CoveragePassCountDto"
            }
          },
          "surfaces": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CoverageSurfaceDto"
            }
          },
          "entrypoints": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CoverageEntrypointDto"
            }
          }
        },
        "required": [
          "name",
          "rootPath",
          "symbols",
          "analysed",
          "previouslyAnalysed",
          "passes",
          "surfaces",
          "entrypoints"
        ]
      },
      "ScanCoverageDto": {
        "type": "object",
        "properties": {
          "version": {
            "type": "number",
            "description": "Record format version."
          },
          "passes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CoveragePassDto"
            }
          },
          "applications": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApplicationCoverageDto"
            }
          }
        },
        "required": ["version", "passes", "applications"]
      },
      "RestPentestReportDto": {
        "type": "object",
        "properties": {
          "scan_id": {
            "type": "string",
            "format": "uuid"
          },
          "summary": {
            "nullable": true,
            "description": "The executive summary; null until one is generated",
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/ExecSummaryResponseDto"
              }
            ]
          },
          "coverage": {
            "nullable": true,
            "description": "What the scan analysed: each application's attack surfaces and entry points; null when none was recorded",
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/ScanCoverageDto"
              }
            ]
          }
        },
        "required": ["scan_id", "summary", "coverage"]
      }
    }
  },
  "security": [
    {
      "api-key": []
    }
  ]
}
