{ "openapi": "3.1.0", "info": { "title": "Walrus API", "version": "1.0.0", "description": "Walrus is a policy- and identity-aware ingress engine for software packages. It discovers, caches, and serves package binaries based on policy expressed in configuration files." }, "servers": [ { "url": "/" } ], "components": { "schemas": { "LandingPageResponse": { "type": "string" }, "ListPackagesResponse": { "type": "object", "properties": { "packages": { "type": "array", "items": { "$ref": "#/components/schemas/Package" } } }, "required": [ "packages" ] }, "Package": { "type": "object", "properties": { "name": { "type": "string" }, "display_name": { "type": "string" }, "vendor": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] } }, "required": [ "name", "display_name", "vendor" ] }, "ListGroupsResponse": { "type": "object", "properties": { "package": { "type": "string" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/VersionGroupSummary" } } }, "required": [ "package", "groups" ] }, "VersionGroupSummary": { "type": "object", "properties": { "group": { "type": "string", "description": "Version group label (e.g. `21`)" }, "is_lts": { "type": "boolean" }, "latest_available": { "type": [ "string", "null" ], "description": "Latest cached version free of known critical (CVSS >= 9.0) CVEs. Null means no version in the group is free of them — nothing safe to recommend, not nothing cached. Per-version CVE detail: /packages/{name}/vulns." } }, "required": [ "group", "is_lts", "latest_available" ] }, "Error": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "ListVersionsResponse": { "type": "object", "properties": { "package": { "type": "string" }, "version_groups": { "type": "array", "items": { "type": "string" } }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/Version" } } }, "required": [ "package", "version_groups", "versions" ] }, "Version": { "type": "object", "properties": { "version": { "type": "string" }, "version_group": { "type": "string" }, "is_lts": { "type": "boolean" }, "status": { "type": "string", "enum": [ "available", "blocked", "cooling_off" ], "description": "Whether the version can be fetched. `blocked` is a concrete match to a known critical CVE (any CVSS base score — v3, v4, or v2 — >= 9.0, or score-less CRITICAL) and takes precedence. `cooling_off` means no platform is servable yet because every candidate artifact is inside its release embargo. `available` means at least one platform is downloadable now, or is pending for ordinary sync reasons." }, "available_at": { "type": [ "string", "null" ], "format": "date-time", "description": "For `cooling_off`, when the first platform leaves its embargo. Null for every other status." }, "platforms": { "type": "array", "items": { "$ref": "#/components/schemas/Platform" } } }, "required": [ "version", "version_group", "is_lts", "status", "platforms" ] }, "Platform": { "type": "object", "properties": { "os": { "type": "string" }, "arch": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "downloading", "available", "failed", "removed", "cooling_off" ], "description": "Artifact lifecycle state, except that an artifact still inside its release embargo reports `cooling_off` rather than the `pending` it is stored as — the two are indistinguishable otherwise, and mean very different things to a caller." }, "available_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When a `cooling_off` artifact becomes servable. Null for every other status." } }, "required": [ "os", "arch", "status" ] }, "LatestArtifactResponse": { "type": "object", "properties": { "package": { "type": "string" }, "version_group": { "type": "string" }, "version": { "type": "string" }, "is_lts": { "type": "boolean" }, "artifact": { "$ref": "#/components/schemas/Artifact" } }, "required": [ "package", "version_group", "version", "is_lts", "artifact" ] }, "Artifact": { "type": "object", "properties": { "os": { "type": "string" }, "arch": { "type": "string" }, "filename": { "type": "string" }, "file_size": { "type": [ "integer", "null" ] }, "checksum": { "type": [ "string", "null" ] }, "checksum_type": { "type": [ "string", "null" ], "example": "sha256" }, "download_url": { "type": "string" }, "requires_range": { "type": "boolean", "description": "Whether this artifact can only be fetched with a `Range` request. An unranged GET of one is refused with 400 `range_required` rather than served, because a single request cannot complete inside the 3600s server deadline at this size. A ranged GET whose `If-Range` no longer matches is refused too, with 400 `stale_range_validator`, since the whole representation the RFC would have us send is the thing being refused. Published here so a client decides before it starts downloading.", "example": false }, "upstream_url": { "type": [ "string", "null" ], "description": "URL the source bytes were fetched from. For an untransformed artifact this is also where the served bytes came from; for a transformed one it is the start of the provenance chain." }, "source_checksum": { "type": [ "string", "null" ], "description": "Digest of the bytes upstream published, verified before any transform ran. Null means the served bytes are upstream's own and `checksum` already covers them." }, "source_file_size": { "type": [ "integer", "null" ], "description": "Byte count of the upstream source. Null on untransformed artifacts." }, "transform": { "type": [ "string", "null" ], "description": "Versioned identity of the conversion that produced the served bytes (e.g. `tar-bz2-to-zip@1`). Null means the artifact is untransformed.", "example": "tar-bz2-to-zip@1" } }, "required": [ "os", "arch", "filename", "download_url", "requires_range" ] }, "SyncingResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "syncing" }, "message": { "type": "string" } }, "required": [ "status", "message" ] }, "CoolingOffError": { "type": "object", "properties": { "error": { "type": "string" }, "available_at": { "type": "string", "format": "date-time" } }, "required": [ "error", "available_at" ] }, "BlockedVersionError": { "type": "object", "properties": { "error": { "type": "string" }, "blocked_by": { "type": "object", "properties": { "cve_id": { "type": "string" }, "matched_because": { "type": "string", "description": "The version comparison that matched, e.g. `0.10.10 == 0.10.10` or `2.55.0 < 2.56.0`. Says so explicitly when the served version was normalised before comparison.", "example": "0.10.10 == 0.10.10" }, "severity": { "type": [ "string", "null" ] }, "severity_source": { "type": [ "string", "null" ], "description": "Which CVSS version produced `severity`: nvd-cvss-v3 | nvd-cvss-v4 | nvd-cvss-v2." }, "cvss_v3_score": { "type": [ "number", "null" ] }, "cvss_v4_score": { "type": [ "number", "null" ] }, "cvss_v2_score": { "type": [ "number", "null" ] }, "is_kev": { "type": "boolean", "description": "Known exploited in the wild (CISA KEV). Reported, but not itself a reason for the block." }, "fixed_in": { "type": [ "string", "null" ], "description": "The version the advisory says fixes this, when it names one. Where to go next." } }, "required": [ "cve_id", "matched_because", "severity", "severity_source", "cvss_v3_score", "cvss_v4_score", "cvss_v2_score", "is_kev", "fixed_in" ], "description": "The CVE that caused the refusal. Where several critical CVEs match, this is the highest-scoring one; the rest are listed by GET /api/v1/packages/{name}/vulns. Absent only when walrus cannot describe the block it just made — the refusal itself is never conditional on being explainable, so treat a missing `blocked_by` as a block with an unavailable explanation, never as a softer refusal." } }, "required": [ "error" ] }, "VulnsResponse": { "type": "object", "properties": { "query": { "type": "object", "properties": { "product": { "type": "string" }, "version": { "type": [ "string", "null" ] } }, "required": [ "product", "version" ] }, "match": { "$ref": "#/components/schemas/VulnMatch" }, "vulns": { "type": "array", "items": { "$ref": "#/components/schemas/VulnItem" } }, "unmatched_vulns": { "type": "array", "items": { "$ref": "#/components/schemas/VulnItem" } }, "counts": { "$ref": "#/components/schemas/VulnCounts" }, "version_parse_warning": { "type": "string" }, "data_freshness": { "$ref": "#/components/schemas/DataFreshness" }, "disclaimer": { "type": "string" } }, "required": [ "query", "match", "vulns", "counts", "data_freshness", "disclaimer" ] }, "VulnMatch": { "type": "object", "properties": { "resolved": { "type": "boolean" }, "product_slug": { "type": [ "string", "null" ], "description": "Resolved walrus package name" }, "display_name": { "type": [ "string", "null" ] }, "confidence": { "type": [ "number", "null" ] }, "method": { "type": [ "string", "null" ], "enum": [ "slug-exact", "alias-exact", "fuzzy", null ] }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/MatchCandidate" } } }, "required": [ "resolved", "product_slug", "display_name", "confidence", "method", "candidates" ] }, "MatchCandidate": { "type": "object", "properties": { "slug": { "type": "string", "description": "Walrus package name" }, "display_name": { "type": "string" }, "score": { "type": "number" } }, "required": [ "slug", "display_name", "score" ] }, "VulnItem": { "type": "object", "properties": { "cve_id": { "type": "string" }, "severity": { "type": [ "string", "null" ] }, "severity_source": { "type": [ "string", "null" ] }, "cvss_v3_score": { "type": [ "number", "null" ] }, "cvss_v4_score": { "type": [ "number", "null" ] }, "cvss_v2_score": { "type": [ "number", "null" ] }, "summary": { "type": [ "string", "null" ] }, "affected": { "type": "object", "properties": { "range": { "type": "string" }, "matched_because": { "type": [ "string", "null" ] } }, "required": [ "range", "matched_because" ] }, "fixed_in": { "type": [ "string", "null" ] }, "is_kev": { "type": "boolean" }, "sources": { "type": "array", "items": { "type": "string" } }, "references": { "type": "array", "items": { "type": "string" } }, "suppression": { "type": [ "object", "null" ], "properties": { "reason": { "type": "string" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "reason", "expires_at" ], "description": "Active operator assertion excluding this CVE from the download gate. The advisory remains visible." } }, "required": [ "cve_id", "severity", "severity_source", "cvss_v3_score", "cvss_v4_score", "cvss_v2_score", "summary", "affected", "fixed_in", "is_kev", "sources", "references", "suppression" ] }, "VulnCounts": { "type": "object", "properties": { "total": { "type": "integer" }, "critical": { "type": "integer" }, "high": { "type": "integer" }, "medium": { "type": "integer" }, "low": { "type": "integer" }, "kev": { "type": "integer" } }, "required": [ "total", "critical", "high", "medium", "low", "kev" ] }, "DataFreshness": { "type": "object", "properties": { "nvd_last_sync": { "type": [ "string", "null" ] }, "kev_last_sync": { "type": [ "string", "null" ] }, "osv_last_sync": { "type": [ "string", "null" ] }, "cvss_last_sync": { "type": [ "string", "null" ] } }, "required": [ "nvd_last_sync", "kev_last_sync", "osv_last_sync", "cvss_last_sync" ] }, "ProductSearchResponse": { "type": "object", "properties": { "query": { "type": "string" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ProductSearchResult" } } }, "required": [ "query", "results" ] }, "ProductSearchResult": { "type": "object", "properties": { "slug": { "type": "string" }, "display_name": { "type": "string" }, "score": { "type": "number" } }, "required": [ "slug", "display_name", "score" ] }, "VulnProductResponse": { "type": "object", "properties": { "name": { "type": "string" }, "display_name": { "type": "string" }, "vendor": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "tracked": { "type": "boolean" }, "aliases": { "type": "array", "items": { "type": "object", "properties": { "alias": { "type": "string" }, "source": { "type": "string" } }, "required": [ "alias", "source" ] } }, "cpes": { "type": "array", "items": { "type": "object", "properties": { "cpe_vendor": { "type": "string" }, "cpe_product": { "type": "string" }, "is_primary": { "type": "boolean" } }, "required": [ "cpe_vendor", "cpe_product", "is_primary" ] } }, "osv": { "type": [ "object", "null" ], "properties": { "ecosystem": { "type": "string" }, "name": { "type": "string" } }, "required": [ "ecosystem", "name" ] }, "cve_count": { "type": "integer", "minimum": 0 } }, "required": [ "name", "display_name", "vendor", "description", "website", "tracked", "aliases", "cpes", "osv", "cve_count" ] }, "CveDetailResponse": { "type": "object", "properties": { "cve_id": { "type": "string" }, "published_at": { "type": [ "string", "null" ] }, "modified_at": { "type": [ "string", "null" ] }, "severity": { "type": [ "string", "null" ] }, "severity_source": { "type": [ "string", "null" ] }, "cvss_v3_score": { "type": [ "number", "null" ] }, "cvss_v3_vector": { "type": [ "string", "null" ] }, "cvss_v4_score": { "type": [ "number", "null" ] }, "cvss_v4_vector": { "type": [ "string", "null" ] }, "cvss_v2_score": { "type": [ "number", "null" ] }, "cvss_v2_vector": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "is_kev": { "type": "boolean" }, "kev_added_at": { "type": [ "string", "null" ] }, "affected_products": { "type": "array", "items": { "$ref": "#/components/schemas/CveAffectedProduct" } }, "references": { "type": "array", "items": { "type": "string" } }, "data_freshness": { "$ref": "#/components/schemas/DataFreshness" }, "disclaimer": { "type": "string" } }, "required": [ "cve_id", "published_at", "modified_at", "severity", "severity_source", "cvss_v3_score", "cvss_v3_vector", "cvss_v4_score", "cvss_v4_vector", "cvss_v2_score", "cvss_v2_vector", "description", "is_kev", "kev_added_at", "affected_products", "references", "data_freshness", "disclaimer" ] }, "CveAffectedProduct": { "type": "object", "properties": { "slug": { "type": "string" }, "display_name": { "type": "string" }, "range": { "type": "string" }, "fixed_in": { "type": [ "string", "null" ] }, "source": { "type": "string" } }, "required": [ "slug", "display_name", "range", "fixed_in", "source" ] }, "AvailabilityHistoryResponse": { "type": "object", "properties": { "package": { "type": "string" }, "version": { "type": [ "string", "null" ] }, "transitions": { "type": "array", "items": { "$ref": "#/components/schemas/AvailabilityTransition" } } }, "required": [ "package", "version", "transitions" ] }, "AvailabilityTransition": { "type": "object", "properties": { "version": { "type": "string" }, "status": { "type": "string", "enum": [ "blocked", "available" ] }, "cve_id": { "type": [ "string", "null" ], "description": "The CVE that caused a `blocked` transition. Null on `available`." }, "cvss_v3_score": { "type": [ "number", "null" ], "description": "CVSS v3 base score of the blocking CVE at transition time, when stored. A block may be explained by v4 or v2 instead — see `severity_source`." }, "cvss_v4_score": { "type": [ "number", "null" ], "description": "CVSS v4 base score of the blocking CVE at transition time, when stored." }, "cvss_v2_score": { "type": [ "number", "null" ], "description": "CVSS v2 base score of the blocking CVE at transition time, when stored." }, "severity": { "type": [ "string", "null" ] }, "severity_source": { "type": [ "string", "null" ], "description": "Which CVSS version produced `severity`: nvd-cvss-v3 | nvd-cvss-v4 | nvd-cvss-v2. Null on `available`, on unscored rows, and on events recorded before this column existed." }, "source": { "type": "string", "description": "Ingestion that produced the change: nvd | kev | osv | cvss | backfill.", "example": "cvss" }, "trigger": { "type": "string", "description": "`internal` for a scheduled run, `admin` for an operator.", "example": "internal" }, "at": { "type": "string", "format": "date-time" } }, "required": [ "version", "status", "cve_id", "cvss_v3_score", "cvss_v4_score", "cvss_v2_score", "severity", "severity_source", "source", "trigger", "at" ] }, "PackageVulnsResponse": { "type": "object", "properties": { "package": { "type": "string" }, "tracked": { "type": "boolean" }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/PackageVersionVulns" } }, "data_freshness": { "$ref": "#/components/schemas/DataFreshness" }, "disclaimer": { "type": "string" } }, "required": [ "package", "tracked", "versions", "data_freshness", "disclaimer" ] }, "PackageVersionVulns": { "type": "object", "properties": { "version": { "type": "string" }, "version_group": { "type": "string" }, "counts": { "$ref": "#/components/schemas/VulnCounts" }, "vulns": { "type": "array", "items": { "$ref": "#/components/schemas/PackageVersionVuln" } } }, "required": [ "version", "version_group", "counts", "vulns" ] }, "PackageVersionVuln": { "type": "object", "properties": { "cve_id": { "type": "string" }, "severity": { "type": [ "string", "null" ] }, "fixed_in": { "type": [ "string", "null" ] }, "is_kev": { "type": "boolean" }, "matched_because": { "type": [ "string", "null" ] }, "suppression": { "type": [ "object", "null" ], "properties": { "reason": { "type": "string" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "reason", "expires_at" ] } }, "required": [ "cve_id", "severity", "fixed_in", "is_kev", "matched_because", "suppression" ] }, "HealthResponse": { "type": "object", "properties": { "isAvailable": { "type": "boolean", "example": true, "description": "Whether the application is wholly available. Dependency degradations do not change this value, and it remains true during the startup grace period." }, "gitUrl": { "type": "string", "format": "uri" }, "ts": { "type": "string", "format": "date-time", "description": "Time this response was generated." }, "started": { "type": "string", "format": "date-time", "description": "Application startup time." }, "inGracePeriod": { "type": "boolean", "description": "Whether the 300-second startup availability grace period is active." }, "version": { "type": "string", "example": "0.2.0" } }, "required": [ "isAvailable", "gitUrl", "ts", "started", "inGracePeriod", "version" ] }, "StatusResponse": { "allOf": [ { "$ref": "#/components/schemas/HealthResponse" }, { "type": "object", "properties": { "vuln_data_freshness": { "allOf": [ { "$ref": "#/components/schemas/DataFreshness" }, { "type": [ "object", "null" ] } ] }, "vuln_sync_status": { "$ref": "#/components/schemas/VulnSyncStatus" }, "cve_suppressions": { "$ref": "#/components/schemas/CveSuppressionStatus" }, "egress": { "$ref": "#/components/schemas/EgressStatus" }, "upstream_credentials": { "$ref": "#/components/schemas/UpstreamCredentials" }, "degradations": { "type": "array", "items": { "$ref": "#/components/schemas/Degradation" }, "description": "Parts of the system currently not doing their job unattended — stale or failing vulnerability ingestion, stuck or disabled autonomous backfills. Empty means self-healing is healthy. Shown as a banner on the admin UI." }, "base_path": { "type": "string", "description": "Effective WALRUS_BASE_PATH (WAL-117). Empty string means walrus is mounted at root, today's default. Every link this response's own request reached — including this one — already carries it.", "example": "" } }, "required": [ "vuln_data_freshness", "vuln_sync_status", "cve_suppressions", "egress", "upstream_credentials", "degradations", "base_path" ] } ] }, "VulnSyncStatus": { "type": [ "object", "null" ], "properties": { "nvd": { "$ref": "#/components/schemas/VulnSourceStatus" }, "kev": { "$ref": "#/components/schemas/VulnSourceStatus" }, "osv": { "$ref": "#/components/schemas/VulnSourceStatus" }, "cvss": { "$ref": "#/components/schemas/VulnSourceStatus" } }, "required": [ "nvd", "kev", "osv", "cvss" ] }, "VulnSourceStatus": { "type": "object", "properties": { "last_attempt": { "type": [ "string", "null" ] }, "last_success": { "type": [ "string", "null" ] }, "last_failure": { "type": [ "string", "null" ] }, "last_ok": { "type": [ "boolean", "null" ] } }, "required": [ "last_attempt", "last_success", "last_failure", "last_ok" ] }, "CveSuppressionStatus": { "type": [ "object", "null" ], "properties": { "active_count": { "type": "integer" }, "next_expiry": { "type": [ "string", "null" ], "format": "date-time", "description": "Soonest expiry among active suppressions that have one; null when every active suppression stands until revoked." } }, "required": [ "active_count", "next_expiry" ], "description": "Operator suppressions currently excluding a CVE from the critical-CVE gate. A suppression is a deliberate, audited decision rather than a fault, so it is reported here in its own right and never as a degradation. Null if unreadable." }, "EgressStatus": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "direct", "rules", "strict" ], "description": "Effective WALRUS_EGRESS_MODE governing outbound public-internet egress." }, "rule_count": { "type": "integer", "description": "Rules loaded from WALRUS_EGRESS_RULES. Never rule content or header values — see GET /admin/v1/egress?url= for a dry-run of what a specific URL would do." } }, "required": [ "mode", "rule_count" ], "description": "Enterprise egress rewriting state (WAL-113). Mode and rule count only, safe to expose publicly; nothing here reveals a rule's match/rewrite targets or header values." }, "UpstreamCredentials": { "type": "object", "properties": { "nvd_api_key": { "type": "boolean", "description": "Whether NVD_API_KEY is set. False means NVD ingestion is limited to 4 requests/30s instead of 45: runs take far longer and are likelier to be cut off by the scheduler's attempt deadline. Presence only, never the value." } }, "required": [ "nvd_api_key" ], "description": "Optional upstream API credentials this process holds. Absence is a supported configuration (walrus runs keyless) rather than a fault, so it is reported here in its own right and never as a degradation. GITHUB_TOKEN is deliberately not reported: it is mounted only into the walrus-sync job, so its absence here says nothing about the deployment — that job warns about it in its own boot log." }, "Degradation": { "type": "object", "properties": { "component": { "type": "string", "example": "vuln-sync-nvd" }, "reason": { "type": "string" } }, "required": [ "component", "reason" ] }, "MetricsResponse": { "type": "string" } }, "parameters": {} }, "paths": { "/": { "get": { "summary": "Walrus landing page", "operationId": "landingPage", "tags": [ "Utility" ], "responses": { "200": { "description": "Public landing page with version and service entry points", "content": { "text/html": { "schema": { "$ref": "#/components/schemas/LandingPageResponse" } } } } } } }, "/api/v1/packages/": { "get": { "summary": "List enabled packages", "operationId": "listPackages", "tags": [ "Packages" ], "responses": { "200": { "description": "List of enabled packages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPackagesResponse" } } } } } } }, "/api/v1/packages/{name}/groups": { "get": { "summary": "List version groups for a package", "operationId": "listVersionGroups", "tags": [ "Packages" ], "parameters": [ { "schema": { "type": "string", "description": "Package name (e.g. `openjdk`, `golang`, `uv`)" }, "required": true, "description": "Package name (e.g. `openjdk`, `golang`, `uv`)", "name": "name", "in": "path" }, { "schema": { "type": "string", "description": "Operating system (e.g. `linux`, `mac`, `windows`)" }, "required": false, "description": "Operating system (e.g. `linux`, `mac`, `windows`)", "name": "os", "in": "query" }, { "schema": { "type": "string", "description": "CPU architecture (e.g. `x86_64`, `aarch64`)" }, "required": false, "description": "CPU architecture (e.g. `x86_64`, `aarch64`)", "name": "arch", "in": "query" } ], "responses": { "200": { "description": "Every version group for the package, newest first. A group with nothing currently servable — all versions embargoed or CVE-blocked — is still listed, with `latest_available: null`. A platform filter narrows which artifacts count as servable, not which groups appear.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListGroupsResponse" } } } }, "404": { "description": "Package not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/packages/{name}/versions": { "get": { "summary": "List versions for a package", "operationId": "listVersions", "tags": [ "Packages" ], "parameters": [ { "schema": { "type": "string", "description": "Package name (e.g. `openjdk`, `golang`, `uv`)" }, "required": true, "description": "Package name (e.g. `openjdk`, `golang`, `uv`)", "name": "name", "in": "path" }, { "schema": { "type": "boolean", "description": "If true, return only LTS versions" }, "required": false, "description": "If true, return only LTS versions", "name": "lts", "in": "query" } ], "responses": { "200": { "description": "Versions with platform availability. Both the version and each platform report `cooling_off` with an `available_at` while inside the release embargo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListVersionsResponse" } } } }, "404": { "description": "Package not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/packages/{name}/versions/{group}/latest": { "get": { "summary": "Get latest artifact for a version group and platform", "operationId": "getLatestArtifact", "tags": [ "Packages" ], "parameters": [ { "schema": { "type": "string", "description": "Package name" }, "required": true, "description": "Package name", "name": "name", "in": "path" }, { "schema": { "type": "string", "description": "Version group (e.g. `21` for Java 21.x)" }, "required": true, "description": "Version group (e.g. `21` for Java 21.x)", "name": "group", "in": "path" }, { "schema": { "type": "string", "description": "Operating system (e.g. `linux`, `mac`, `windows`)" }, "required": false, "description": "Operating system (e.g. `linux`, `mac`, `windows`)", "name": "os", "in": "query" }, { "schema": { "type": "string", "description": "CPU architecture (e.g. `x86_64`, `aarch64`)" }, "required": false, "description": "CPU architecture (e.g. `x86_64`, `aarch64`)", "name": "arch", "in": "query" } ], "responses": { "200": { "description": "Latest available artifact", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LatestArtifactResponse" } } } }, "202": { "description": "No data cached yet; sync triggered. Retry after the indicated interval.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer", "example": 30 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncingResponse" } } } }, "404": { "description": "Package, group, or artifact not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Nothing in the group is servable yet because the candidates are within their cooling-off period. Distinct from 202 (not synced yet) and 404 (nothing safe exists).", "headers": { "Retry-After": { "description": "Seconds until the earliest artifact in the group is released", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoolingOffError" } } } } } } }, "/download/{package}/{version}/{os}/{arch}": { "get": { "summary": "Download a binary", "operationId": "downloadArtifact", "tags": [ "Download" ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "package", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "version", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "os", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "arch", "in": "path" } ], "responses": { "200": { "description": "Binary file stream", "headers": { "Content-Disposition": { "description": "attachment; filename=\"\"", "schema": { "type": "string" } }, "Content-Length": { "schema": { "type": "integer" } }, "X-Checksum-Sha256": { "description": "SHA-256 checksum (if available)", "schema": { "type": "string" } }, "X-Checksum-Sha1": { "description": "SHA-1 checksum (if available)", "schema": { "type": "string" } }, "X-Checksum-Sha512": { "description": "SHA-512 checksum (if available)", "schema": { "type": "string" } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "Version is blocked by the critical-CVE gate. The body names the advisory, the version comparison that matched it, and the fixed version to move to when the advisory names one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockedVersionError" } } } }, "404": { "description": "Artifact not found or not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "423": { "description": "Artifact is within the cooling-off period and not yet released", "headers": { "Retry-After": { "description": "Seconds until the artifact is released", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoolingOffError" } } } } } } }, "/api/v1/vulns": { "get": { "summary": "Look up known CVEs for a product/version", "operationId": "queryVulns", "tags": [ "Vulnerabilities" ], "parameters": [ { "schema": { "type": "string", "description": "Product name or alias (e.g. `openjdk`, `npp`)" }, "required": true, "description": "Product name or alias (e.g. `openjdk`, `npp`)", "name": "product", "in": "query" }, { "schema": { "type": "string", "description": "Version to range-check against" }, "required": false, "description": "Version to range-check against", "name": "version", "in": "query" }, { "schema": { "type": "boolean", "description": "Also return CVEs whose ranges did not match the version" }, "required": false, "description": "Also return CVEs whose ranges did not match the version", "name": "include_unmatched", "in": "query" } ], "responses": { "200": { "description": "Resolution + matching CVEs. Unresolved products return 200 with candidates and empty vulns.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VulnsResponse" } } } }, "400": { "description": "Missing `product` parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/vulns/products/search": { "get": { "summary": "Autocomplete product names/aliases", "operationId": "searchProducts", "tags": [ "Vulnerabilities" ], "parameters": [ { "schema": { "type": "string", "description": "Search prefix/term" }, "required": true, "description": "Search prefix/term", "name": "q", "in": "query" } ], "responses": { "200": { "description": "Ranked product matches (top 10)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductSearchResponse" } } } }, "400": { "description": "Missing `q` parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/vulns/products/{name}": { "get": { "summary": "Get vulnerability product metadata", "operationId": "getVulnProduct", "tags": [ "Vulnerabilities" ], "parameters": [ { "schema": { "type": "string", "description": "Package name (e.g. `openjdk`, `golang`, `uv`)" }, "required": true, "description": "Package name (e.g. `openjdk`, `golang`, `uv`)", "name": "name", "in": "path" } ], "responses": { "200": { "description": "Package metadata, aliases, CPEs, OSV mapping, and distinct CVE count", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VulnProductResponse" } } } }, "404": { "description": "Unknown package", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/cves/{cveId}": { "get": { "summary": "CVE detail", "operationId": "getCve", "tags": [ "Vulnerabilities" ], "parameters": [ { "schema": { "type": "string", "description": "CVE id, e.g. CVE-2023-40031" }, "required": true, "description": "CVE id, e.g. CVE-2023-40031", "name": "cveId", "in": "path" } ], "responses": { "200": { "description": "CVE metadata, KEV status, affected products, references", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CveDetailResponse" } } } }, "400": { "description": "Malformed CVE id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown CVE (or affects no tracked package)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/packages/{name}/availability": { "get": { "summary": "Recorded download-availability transitions for a package's versions", "operationId": "getAvailabilityHistory", "tags": [ "Vulnerabilities" ], "parameters": [ { "schema": { "type": "string", "description": "Package name" }, "required": true, "description": "Package name", "name": "name", "in": "path" }, { "schema": { "type": "string", "description": "Limit to one version's history. Omit for the package's recent changes." }, "required": false, "description": "Limit to one version's history. Omit for the package's recent changes.", "name": "version", "in": "query" } ], "responses": { "200": { "description": "Gate transitions, newest first. Rows are written only when a version's status actually changes, and record which ingestion caused it. This is history, not a re-derivation of the current CVE rows — it answers when a version became blocked and why.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailabilityHistoryResponse" } } } }, "404": { "description": "Unknown package", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/packages/{name}/vulns": { "get": { "summary": "CVEs affecting a package's cached versions", "operationId": "getPackageVulns", "tags": [ "Vulnerabilities" ], "parameters": [ { "schema": { "type": "string", "description": "Package name (e.g. `openjdk`, `golang`, `uv`)" }, "required": true, "description": "Package name (e.g. `openjdk`, `golang`, `uv`)", "name": "name", "in": "path" }, { "schema": { "type": "string", "description": "Restrict to a single cached version" }, "required": false, "description": "Restrict to a single cached version", "name": "version", "in": "query" } ], "responses": { "200": { "description": "Per-cached-version CVE counts + matches. Untracked packages return tracked:false.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageVulnsResponse" } } } }, "404": { "description": "Unknown package", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/health": { "get": { "summary": "Deployment availability check", "operationId": "health", "tags": [ "Utility" ], "responses": { "200": { "description": "Application is available, including during its startup grace period", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } }, "503": { "description": "Application is wholly unavailable after its startup grace period", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/app/health": { "get": { "summary": "Deployment availability check alias", "operationId": "appHealth", "tags": [ "Utility" ], "responses": { "200": { "description": "Application is available, including during its startup grace period", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } }, "503": { "description": "Application is wholly unavailable after its startup grace period", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/app/status": { "get": { "summary": "Detailed application status", "operationId": "appStatus", "tags": [ "Utility" ], "responses": { "200": { "description": "Availability plus operational degradation details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusResponse" } } } }, "503": { "description": "Application is wholly unavailable after its startup grace period", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusResponse" } } } } } } }, "/metrics": { "get": { "summary": "Prometheus metrics", "operationId": "metrics", "tags": [ "Utility" ], "responses": { "200": { "description": "Prometheus text exposition with immediate access to the last background-refreshed database snapshot", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/MetricsResponse" } } } } } } }, "/api": { "get": { "summary": "API documentation", "operationId": "apiDocs", "tags": [ "Utility" ], "responses": { "200": { "description": "API documentation as Markdown or HTML depending on Accept header", "content": { "text/markdown": { "schema": { "type": "string" } }, "text/html": { "schema": { "type": "string" } } } } } } }, "/openapi.json": { "get": { "summary": "OpenAPI specification", "operationId": "openApiSpec", "tags": [ "Utility" ], "responses": { "200": { "description": "OpenAPI 3.1.0 specification for this API", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "webhooks": {} }