{
  "openapi": "3.1.0",
  "info": {
    "title": "Dependency Preflight API",
    "version": "0.1.0",
    "description": "Known-vulnerability, release-age, install-script, and package-metadata preflight for exact npm and PyPI package versions. Not a security guarantee or legal opinion."
  },
  "servers": [
    {
      "url": "https://api.preflightstack.com",
      "description": "Public Base Sepolia x402 testnet pilot"
    },
    {
      "url": "http://127.0.0.1:4021",
      "description": "Local development"
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Check API health",
        "responses": {
          "200": {
            "description": "The API process is healthy.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "service",
                    "version",
                    "time"
                  ],
                  "properties": {
                    "status": {
                      "const": "ok"
                    },
                    "service": {
                      "const": "dependency-preflight-api"
                    },
                    "version": {
                      "type": "string"
                    },
                    "time": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/demo": {
      "get": {
        "operationId": "getDemo",
        "summary": "Return a fixed preflight example without querying upstream services",
        "responses": {
          "200": {
            "description": "Fixed example response"
          }
        }
      }
    },
    "/v1/policies": {
      "get": {
        "operationId": "listPolicies",
        "summary": "List the version-one policy and decision behavior",
        "responses": {
          "200": {
            "description": "Supported policies"
          }
        }
      }
    },
    "/v1/dependency-preflight": {
      "post": {
        "operationId": "dependencyPreflight",
        "summary": "Evaluate up to ten exact npm or PyPI package versions",
        "description": "When X402_MODE=testnet, this route requires a $0.02 USDC x402 payment on Base Sepolia. It remains free when payments are disabled.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PreflightRequest"
              },
              "example": {
                "ecosystem": "npm",
                "packages": [
                  {
                    "name": "example-package",
                    "version": "1.0.0"
                  }
                ],
                "policy": "balanced"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Completed or explicitly partial preflight",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreflightResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "402": {
            "description": "x402 payment is required or payment verification/settlement failed"
          },
          "413": {
            "description": "Request body exceeds 32 KB"
          },
          "415": {
            "description": "Content-Type is not application/json"
          },
          "500": {
            "description": "Unexpected internal failure"
          },
          "503": {
            "description": "The concurrent preflight limit is reached; retry after the indicated delay"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PackageRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "version"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 214
          },
          "version": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          }
        }
      },
      "PreflightRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "ecosystem",
          "packages"
        ],
        "properties": {
          "ecosystem": {
            "type": "string",
            "enum": [
              "npm",
              "pypi"
            ]
          },
          "packages": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/PackageRequest"
            }
          },
          "policy": {
            "type": "string",
            "enum": [
              "balanced"
            ],
            "default": "balanced"
          },
          "license_allowlist": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "type": "string"
            }
          },
          "license_denylist": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "type": "string"
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message",
              "retryable",
              "request_id"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "path": {
                "type": "string"
              },
              "retryable": {
                "type": "boolean"
              },
              "request_id": {
                "type": "string"
              }
            }
          }
        }
      },
      "Evidence": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "source",
          "retrieved_at",
          "url"
        ],
        "properties": {
          "source": {
            "type": "string",
            "enum": [
              "npm",
              "pypi",
              "osv"
            ]
          },
          "retrieved_at": {
            "type": "string",
            "format": "date-time"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "cached": {
            "type": "boolean"
          }
        }
      },
      "Vulnerability": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "id",
          "aliases",
          "summary",
          "severity",
          "upstream_severity",
          "fixed_versions",
          "modified_at",
          "url"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "aliases": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "summary": {
            "type": [
              "string",
              "null"
            ]
          },
          "severity": {
            "type": "string",
            "enum": [
              "critical",
              "high",
              "medium",
              "low",
              "unknown"
            ]
          },
          "upstream_severity": {},
          "fixed_versions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "modified_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Finding": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "code",
          "level",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string"
          },
          "level": {
            "type": "string",
            "enum": [
              "review",
              "block"
            ]
          },
          "message": {
            "type": "string"
          }
        }
      },
      "PackageResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "ecosystem",
          "name",
          "requested_version",
          "version_exists",
          "decision",
          "license",
          "lifecycle",
          "install",
          "vulnerabilities",
          "findings",
          "evidence",
          "partial"
        ],
        "properties": {
          "ecosystem": {
            "type": "string",
            "enum": [
              "npm",
              "pypi"
            ]
          },
          "name": {
            "type": "string"
          },
          "requested_version": {
            "type": "string"
          },
          "version_exists": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "decision": {
            "type": "string",
            "enum": [
              "allow",
              "review",
              "block"
            ]
          },
          "license": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "declared",
              "normalized",
              "status"
            ],
            "properties": {
              "declared": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "normalized": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "status": {
                "type": "string",
                "enum": [
                  "allow",
                  "review",
                  "block"
                ]
              }
            }
          },
          "lifecycle": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "deprecated",
              "yanked",
              "latest_version",
              "requested_release_date",
              "latest_release_date"
            ],
            "properties": {
              "deprecated": {
                "type": "boolean"
              },
              "yanked": {
                "type": "boolean"
              },
              "latest_version": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "requested_release_date": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "latest_release_date": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              }
            }
          },
          "install": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "lifecycle_scripts"
            ],
            "properties": {
              "lifecycle_scripts": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "preinstall",
                    "install",
                    "postinstall"
                  ]
                },
                "uniqueItems": true
              }
            }
          },
          "vulnerabilities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Vulnerability"
            }
          },
          "findings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Finding"
            }
          },
          "evidence": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Evidence"
            }
          },
          "partial": {
            "type": "boolean"
          }
        }
      },
      "PreflightResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "request_id",
          "decision",
          "policy",
          "summary",
          "packages",
          "limitations",
          "generated_at"
        ],
        "properties": {
          "request_id": {
            "type": "string"
          },
          "decision": {
            "type": "string",
            "enum": [
              "allow",
              "review",
              "block"
            ]
          },
          "policy": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "name",
              "version"
            ],
            "properties": {
              "name": {
                "const": "balanced"
              },
              "version": {
                "type": "string"
              }
            }
          },
          "summary": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "package_count",
              "allow",
              "review",
              "block",
              "partial"
            ],
            "properties": {
              "package_count": {
                "type": "integer",
                "minimum": 1,
                "maximum": 10
              },
              "allow": {
                "type": "integer",
                "minimum": 0
              },
              "review": {
                "type": "integer",
                "minimum": 0
              },
              "block": {
                "type": "integer",
                "minimum": 0
              },
              "partial": {
                "type": "integer",
                "minimum": 0
              }
            }
          },
          "packages": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10,
            "items": {
              "$ref": "#/components/schemas/PackageResult"
            }
          },
          "limitations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  }
}