Package API endpoints

Public package endpoints

These endpoints are publicly accessible. No authentication is required.

Get package certificate

GET /api/v1/public/packages/:registry/:name/:version

Returns the SIGMA certificate for a specific package version, if one exists.

Path parameters:

• registry — pypi or npm
• name — exact package name
• version — exact version string

Response:

{
  "registrySource": "pypi",
  "packageName": "requests",
  "packageVersion": "2.31.0",
  "distributionSha256": "58cd2187...",
  "councilVerdict": "APPROVED",
  "securityLevel": "CLEAR",
  "retainedWarnings": [],
  "analysisType": "FULL",
  "certifiedAt": "2026-04-15T10:23:41.000Z",
  "certificateId": "pkg_abc123",
  "verifyEndpoint": "https://api.soulbyte.tech/api/v1/public/packages/pypi/requests/2.31.0/verify",
  "registryAdvisoryCount": 0,
  "registryAdvisoryHighestSeverity": null,
  "registryAdvisorySummary": "No known registry security advisories were listed for this exact package version at certification time.",
  "registryAdvisories": []
}

Registry advisories (registryAdvisories, registryAdvisorySummary, counts): factual CVE / advisory rows from the public npm security advisory bulk API (POST JSON body keyed by package name, values are version lists) and from the PyPI JSON release API vulnerabilities field (OSV-backed). This is registry data only — it does not replace the SIGMA council verdict on the package. When the stored certificate has no snapshot yet, the API may still resolve advisories live from those same public endpoints.

analysisType values:

• FULL — complete source analysis performed
• PARTIAL — package exceeded size limits; analysis covers what was accessible
• BINARY_ONLY — no source distribution available; compiled extensions only

Returns 404 if the package has not been certified.

Verify package certificate

GET /api/v1/public/packages/:registry/:name/:version/verify

Returns the full certificate with integrity details. Intended for programmatic verification — agents and tools that need to confirm a package's certification status before invoking code that uses it.

The response includes the distribution SHA256, the file set hash, and the council round identifier. These allow a verifier to independently confirm that the distribution bytes they have match the bytes SIGMA reviewed.

The payload also includes registry advisory fields (registryAdvisories, structured registryAdvisorySummary) resolved from the stored certificate snapshot or, when missing on legacy rows, from the same public npm / PyPI advisory sources described above.

Registry statistics

GET /api/v1/public/packages/stats

Returns a live snapshot of the Package Trust Registry.

Response:

{
  "totalPackagesCertified": 312,
  "totalSubmissionsBenefitingFromCache": 1840,
  "totalCostSavedUsd": 3620,
  "codeSubmissionsWithPackages": 417,
  "coverage": {
    "pypi": {
      "top100": { "tracked": 100, "certified": 67, "percent": 67 },
      "top500": { "tracked": 500, "certified": 189, "percent": 37 },
      "top1000": { "tracked": 1000, "certified": 231, "percent": 23 }
    },
    "npm": {
      "top100": { "tracked": 100, "certified": 41, "percent": 41 }
    }
  }
}

This endpoint powers live coverage metrics. The tracked field shows the benchmark size (the number of packages in the comparison list), and certified shows how many of those are already in the registry.

Developer portal endpoints

These endpoints require developer authentication.

Package preview

POST /api/v1/sigma/dev/drafts/:draftId/package-preview

Fetches the current certification status of all direct dependencies in a draft submission's manifest, without submitting. Used by the developer portal to show the itemised quote before the developer confirms. The response also includes aggregate counts for transitive dependencies discovered during preview.

Response:

{
  "enabled": true,
  "packagesTotal": 8,
  "packagesCertifiedFromCache": 6,
  "packagesToAudit": 1,
  "packagesRejected": 0,
  "packagesUncertified": 1,
  "transitiveDependenciesChecked": 14,
  "transitiveDependenciesUncertified": 3,
  "savingsUsd": 14.00,
  "uncachedCostUsd": 4.00,
  "items": [
    {
      "packageName": "requests",
      "packageVersion": "2.31.0",
      "registrySource": "pypi",
      "dependencyType": "DIRECT",
      "cached": true,
      "status": "CERTIFIED",
      "estimatedComplexityTier": "standard",
      "estimatedPriceUsd": 0,
      "warnings": []
    }
  ]
}

items contains the direct dependency rows shown in the quote UI. transitiveDependenciesChecked and transitiveDependenciesUncertified are aggregate counts across the discovered transitive graph, rather than a nested tree payload.

See also: API surface map, Package Trust Registry.