# Commit — Full Documentation for AI Assistants

> This file supplements /llms.txt with complete API schemas, response
> examples, and integration patterns.

## REST API

### Batch audit (primary endpoint)

POST https://poc-backend.amdal-dev.workers.dev/api/audit
Content-Type: application/json

Request:
  {"packages": ["axios", "zod", "chalk", "express", "lodash"]}

Response (200):
  {
    "count": 5,
    "results": [
      {
        "name": "chalk",
        "ecosystem": "npm",
        "score": 75,
        "maintainers": 1,
        "githubContributors": 35,
        "weeklyDownloads": 354196976,
        "ageYears": 12.8,
        "trend": "stable",
        "daysSinceLastPublish": 270,
        "hasProvenance": false,
        "scorecardScore": 3.8,
        "hasDangerousWorkflow": false,
        "riskFlags": ["CRITICAL: sole npm publisher + >10M/wk"],
        "scoreBreakdown": {
          "longevity": 25,
          "downloadMomentum": 22,
          "releaseConsistency": 13,
          "maintainerDepth": 4,
          "githubBacking": 11,
          "trustedPublishing": 0
        }
      }
    ]
  }

Supports ecosystems: npm (default), pypi, cargo, golang.

For non-npm packages, prefix with ecosystem:
  {"packages": ["pypi:litellm", "cargo:serde", "golang:github.com/gin-gonic/gin"]}

Rate limits:
  Anonymous (no key):   15 req/day per IP (often CGN-shared)
  Free key:             200 req/day
  Developer ($15/mo):   1,000 req/day, batch up to 5 packages
  Pro ($29/mo):         10,000 req/month, batch up to 20 packages
  Enterprise ($199/mo): unlimited

Free keys (no card, 30 seconds): https://getcommit.dev/pricing

Default response is human-readable text. For machine-parseable JSON, send:
  Accept: application/json

With API key:
  Authorization: Bearer sk_commit_YOUR_KEY

### Badge endpoint

GET https://poc-backend.amdal-dev.workers.dev/badge/{package}
GET https://poc-backend.amdal-dev.workers.dev/api/badge/{ecosystem}/{package}

Returns an SVG badge. Ecosystem: npm, pypi, cargo, golang.

Markdown:
  ![Commit Trust](https://poc-backend.amdal-dev.workers.dev/badge/chalk)

### Checkout (Stripe)

GET https://poc-backend.amdal-dev.workers.dev/api/checkout?tier=developer&interval=monthly

Tiers: developer ($15/mo), pro ($29/mo), enterprise ($199/mo).
Intervals: monthly, annual.

## CLI Reference

Install globally:
  npm install -g proof-of-commitment

Or run once:
  npx proof-of-commitment [packages...] [options]

Options:
  --file <path>        Scan manifest (package.json, package-lock.json,
                       yarn.lock, pnpm-lock.yaml, pnpm-workspace.yaml,
                       requirements.txt, Cargo.toml, Cargo.lock,
                       go.mod, go.sum)
  --pypi <packages>    Score PyPI packages
  --cargo <packages>   Score Rust crates
  --golang <packages>  Score Go modules
  --json               JSON output for downstream tools
  --fail-on=<level>    Exit 1 on: critical, risky, or none
  --api-key <key>      Use API key for higher limits

Zero-arg auto-detect:
  cd your-project && npx proof-of-commitment
  # Picks the highest-coverage manifest in cwd

## MCP Server Tools

Remote endpoint: https://poc-backend.amdal-dev.workers.dev/mcp
Protocol: Streamable HTTP (stateless)

### audit_dependencies
Batch risk audit for up to 20 packages across npm, PyPI, Cargo, Go.
Input: { packages: string[], ecosystem?: string }

### audit_github_repo
Whole-repo dependency audit. Fetches package.json and requirements.txt
from the GitHub repo and scores every direct dependency.
Input: { repo: string }   // "owner/repo" or full GitHub URL

### audit_dependency_tree
Transitive npm dependency audit. Walks the dep graph and surfaces
CRITICAL/HIGH packages at each level.
Input: { package: string, depth?: 1 | 2 }   // depth 1 (default) = direct deps; 2 = also traverse CRITICAL/HIGH transitives

### lookup_npm_package
Single npm package behavioral profile.
Input: { name: string }

### lookup_pypi_package
Single PyPI package behavioral profile.
Input: { name: string }

### lookup_cargo_crate
Single Rust crate behavioral profile.
Input: { name: string }

### lookup_go_module
Single Go module behavioral profile.
Input: { module: string }

### lookup_github_repo
GitHub repo commitment score.
Input: { owner: string, repo: string }

### lookup_business
Norwegian business register lookup.
Input: { name: string }

### lookup_business_by_org
Norwegian business register lookup by org number.
Input: { orgnr: string }

### query_commitment
Browser extension behavioral data.
Input: { domain: string }

## GitHub Action

Repository: piiiico/commit-action
Latest: v1.2.0

Minimal CI config:
  name: Supply Chain Audit
  on: [pull_request]
  jobs:
    audit:
      runs-on: ubuntu-latest
      permissions:
        pull-requests: write
      steps:
        - uses: actions/checkout@v4
        - uses: piiiico/commit-action@v1
          with:
            fail-on-critical: true
            comment-on-pr: true

Inputs: packages, packages-file, ecosystem, fail-on-critical,
max-packages, include-dev-dependencies, comment-on-pr, api-key, api-url.

Outputs: has-critical, critical-count, audit-summary.

## IDE Hook Integration

Install for current project:
  poc hook

Install globally:
  poc hook --global

Intercepted commands: npm install, pnpm add, yarn add,
pip install, cargo add, go get.

Default behavior: CRITICAL packages blocked, HIGH packages prompt user.

## Scoring Methodology

Each package scored 0–100 across five dimensions:

1. Longevity (0–25 points)
   How long has the package existed? Older = more established.

2. Download momentum (0–25 points)
   Stable or growing download trends signal healthy adoption.

3. Release consistency (0–20 points)
   Regular releases signal active oversight. Long gaps = risk.

4. Maintainer/publisher depth (0–15 points)
   More publishers = less single-point-of-failure risk.
   1 publisher on a >10M/wk package = CRITICAL.

5. GitHub backing (0–15 points)
   OpenSSF Scorecard integration: code review enforcement,
   branch protection, CI/CD safety.

Risk flag thresholds:
  CRITICAL: 1 npm publisher + >10M weekly downloads
  HIGH: package <1yr old + rapid adoption
  WARN: no release in 12+ months

## Real-World Validation

These attacked packages flag CRITICAL today on the signal their attacks used. The scores were computed after the attacks, not before:
  - axios: attacked March 30, 2026 (sole active npm publisher)
  - LiteLLM (PyPI): attacked March 2026 (sole maintainer)

## Pricing

Anonymous (no key):  15 req/day per IP (often CGN-shared)
Open (free key):     200 req/day, CLI, web audit, MCP (unlimited with key)
Developer $15/mo:    1,000 req/day, batch API (5 packages), monitoring (3 projects)
Pro $29/mo:          10,000 req/month, batch API (20 packages), 10 projects, Slack/webhook alerts
Enterprise $199/mo:  unlimited, hourly scans, SBOM, SSO, SLA

Free keys: https://getcommit.dev/pricing (30 seconds, no credit card)

## Contact

Support, billing, technical: support@getcommit.dev
Licensing, partnerships, content reuse: pico@amdal.dev
GitHub: https://github.com/piiiico/proof-of-commitment