Commit API Reference — Developer Documentation

01

Quick Start

Audit a package in 30 seconds. No API key needed for single-package queries.

# Audit a single npm package (free, no API key)
curl -X POST https://poc-backend.amdal-dev.workers.dev/api/audit \
  -H "Content-Type: application/json" \
  -d '{"packages": ["chalk"]}'

// Audit a single npm package (free, no API key)
const res = await fetch(
  "https://poc-backend.amdal-dev.workers.dev/api/audit",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ packages: ["chalk"] }),
  }
);
const data = await res.json();
console.log(data.results[0]);

# Audit a single npm package (free, no API key)
import requests

resp = requests.post(
    "https://poc-backend.amdal-dev.workers.dev/api/audit",
    json={"packages": ["chalk"]},
)
print(resp.json()["results"][0])

Response

{
  "count": 1,
  "results": [
    {
      "name": "chalk",
      "ecosystem": "npm",
      "score": 74,
      "maintainers": 1,
      "weeklyDownloads": 411000000,
      "ageYears": 12.3,
      "trend": "stable",
      "daysSinceLastPublish": 420,
      "riskFlags": ["CRITICAL"],
      "scoreBreakdown": {
        "longevity": 25,
        "downloadMomentum": 25,
        "releaseConsistency": 14,
        "maintainerDepth": 4,
        "githubBacking": 6
      }
    }
  ]
}

02

Authentication

All endpoints work without authentication. Free tier uses IP-based rate limiting. Upgrade to Commit Pro for an API key and higher limits.

Free No setup required

Requests are rate-limited per IP address. No header required. Single-package audit per request.

Pro $29/mo

Pass your API key as a Bearer token. Unlocks batch audits (up to 20 packages), higher monthly limits, and priority processing.

Authorization: Bearer sk_commit_a3f9b2...

API key format sk_commit_ followed by 32 hex characters. Keys are issued after checkout at getcommit.dev/pricing. Store them securely — they are shown once.

03

Rate Limits

Rate limit headers are returned on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Endpoint	Free	Pro	Enterprise
`POST /api/audit`	200 / day 1 pkg/request	10,000 / month 20 pkgs/request	Unlimited
`POST /api/audit/github`	10 / day	500 / month	Unlimited
`POST /api/graph/npm`	5 / day	200 / month	Unlimited
`GET /badge/npm/:pkg`	Unlimited (24h CDN cache)
`GET /badge/pypi/:pkg`	Unlimited (24h CDN cache)

Free tier resets daily at midnight UTC. Pro tier resets on the first day of each calendar month. When a limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header.

04

Endpoints

POST /api/audit

Score npm or PyPI packages for supply chain risk. Results sorted by score ascending (highest risk first).

Request body

Field	Type	Required	Description
`packages`	string[]	Yes	Package names. Max 1 (free) or 20 (Pro). Mix npm and PyPI names freely when ecosystem is "auto".
`ecosystem`	string	No	`"npm"` \| `"pypi"` \| `"auto"` (default). Auto defaults to npm.

# Batch audit (Pro — requires API key)
curl -X POST https://poc-backend.amdal-dev.workers.dev/api/audit \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_commit_..." \
  -d '{
    "packages": ["axios", "lodash", "express", "chalk"],
    "ecosystem": "npm"
  }'

const res = await fetch(
  "https://poc-backend.amdal-dev.workers.dev/api/audit",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer sk_commit_...",
    },
    body: JSON.stringify({
      packages: ["axios", "lodash", "express", "chalk"],
      ecosystem: "npm",
    }),
  }
);
const { results } = await res.json();
const critical = results.filter(r => r.riskFlags.includes("CRITICAL"));
console.log("Critical packages:", critical.map(r => r.name));

import requests

resp = requests.post(
    "https://poc-backend.amdal-dev.workers.dev/api/audit",
    headers={"Authorization": "Bearer sk_commit_..."},
    json={
        "packages": ["requests", "flask", "django"],
        "ecosystem": "pypi",
    },
)
data = resp.json()
for pkg in data["results"]:
    print(f"{pkg['name']}: {pkg['score']} {pkg['riskFlags']}")

POST /api/audit/github

Fetch dependencies from a GitHub repository and run supply chain risk scoring. Reads package.json and requirements.txt automatically.

Request body

Field	Type	Required	Description
`repo`	string	Yes	GitHub repo as `"owner/repo"` or full URL. E.g. `"facebook/react"` or `"https://github.com/expressjs/express"`.

curl -X POST https://poc-backend.amdal-dev.workers.dev/api/audit/github \
  -H "Content-Type: application/json" \
  -d '{"repo": "vercel/next.js"}'

const res = await fetch(
  "https://poc-backend.amdal-dev.workers.dev/api/audit/github",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ repo: "vercel/next.js" }),
  }
);
const data = await res.json();
// data.repo, data.npmPackages, data.pypiPackages, data.results

Response shape

{
  "repo": "vercel/next.js",
  "npmPackages": 18,
  "pypiPackages": 0,
  "count": 18,
  "results": [ /* same shape as /api/audit results */ ]
}

POST /api/graph/npm

Build a dependency risk graph for an npm package. Returns nodes (packages with scores) and edges (dependency relationships). depth=2 traverses transitive dependencies of risky packages.

Request body

Field	Type	Required	Description
`package`	string	Yes	Root npm package name. E.g. `"express"`.
`depth`	1 \| 2	No	Default 1 (root + direct deps). Depth 2 adds transitive deps of risky packages.

curl -X POST https://poc-backend.amdal-dev.workers.dev/api/graph/npm \
  -H "Content-Type: application/json" \
  -d '{"package": "express", "depth": 1}'

const res = await fetch(
  "https://poc-backend.amdal-dev.workers.dev/api/graph/npm",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ package: "express", depth: 1 }),
  }
);
const { nodes, edges, summary } = await res.json();
console.log(`{summary.criticalCount} CRITICAL packages in tree`);

Response shape

{
  "root": "express",
  "depth": 1,
  "nodes": [
    {
      "name": "express",
      "score": 97,
      "maintainers": 5,
      "weeklyDownloads": 93000000,
      "ageYears": 15.2,
      "trend": "growing",
      "riskFlags": [],
      "depth": 0
    },
    /* direct deps at depth: 1 */
  ],
  "edges": [{ "from": "express", "to": "body-parser" }, ...],
  "summary": {
    "totalNodes": 12,
    "criticalCount": 0,
    "highCount": 1,
    "warnCount": 2,
    "worstScore": 42,
    "criticalTransitivePaths": []
  }
}

GET /badge/npm/:package

GET /badge/pypi/:package

Returns a shields.io-compatible SVG badge with the trust score. CDN-cached for 24 hours. Handles scoped npm packages: /badge/npm/@scope/name.

# Add to your README.md
[![Commit Score](https://poc-backend.amdal-dev.workers.dev/badge/npm/express)](https://getcommit.dev/scan/express)

[![Commit Score](https://poc-backend.amdal-dev.workers.dev/badge/pypi/requests)](https://getcommit.dev)

<a href="https://getcommit.dev/scan/express">
  <img src="https://poc-backend.amdal-dev.workers.dev/badge/npm/express"
       alt="Commit Score" />
</a>

⚠ CRITICAL < 40 high risk 40–59 moderate 60–74 good 75+ healthy not found

05

Response Schema

Every package result from /api/audit and /api/audit/github has the same shape.

Field	Type	Description
`name`	string	Package name as returned by the registry.
`ecosystem`	"npm" \| "pypi"	Package registry.
`score`	number \| null	Trust score 0–100. `null` if package not found or error.
`maintainers`	number \| null	Number of publish-authorized maintainers.
`weeklyDownloads`	number \| null	Weekly download count (npm) or weekly equivalent for PyPI.
`ageYears`	number \| null	Package age in years, rounded to 1 decimal.
`trend`	"growing" \| "stable" \| "declining" \| null	90-day download trend. Growing if ratio > 1.15, declining if < 0.85.
`daysSinceLastPublish`	number \| null	Days since most recent version was published.
`riskFlags`	string[]	`"CRITICAL"` — sole maintainer + >10M downloads/wk. `"HIGH"` — sole maintainer + >1M, or <1yr old + >1M. `"WARN"` — no publish in 365+ days.
`scoreBreakdown`	object \| null	Component scores per the scoring specification: `longevity` (0–25), `downloadMomentum` (0–25), `releaseConsistency` (0–20), `maintainerDepth` (0–15), `githubBacking` (0–15).
`error`	string \| undefined	Present only if the individual package lookup failed (e.g. "not found").

06

Integrations

GitHub Action

Drop into any repo. Auto-detects dependencies from package.json and requirements.txt. Posts results as a PR comment on every dependency change.

# .github/workflows/commit-audit.yml
name: Supply Chain Audit

on:
  push:
    branches: [main]
    paths: [package.json, requirements.txt]
  pull_request:
    paths: [package.json, requirements.txt]

jobs:
  audit:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: actions/checkout@v4

      - name: Commit Supply Chain Audit
        uses: piiiico/proof-of-commitment@main
        with:
          fail-on-critical: false   # set true to block merges
          max-packages: '20'
          comment-on-pr: true       # posts PR comment, updates on re-run

Source: github.com/piiiico/proof-of-commitment

MCP Server

Use Commit directly from Claude, Cursor, or any MCP-compatible AI tool. The remote server is stateless and requires no local setup.

Remote (no install) Streamable HTTP

https://poc-backend.amdal-dev.workers.dev/mcp

Add to your MCP client config. Compatible with Claude Desktop, Continue, and any client supporting Streamable HTTP transport.

Claude Desktop config

{
  "mcpServers": {
    "commit": {
      "url": "https://poc-backend.amdal-dev.workers.dev/mcp",
      "transport": "http"
    }
  }
}

07

Errors

All errors return JSON with an error field. HTTP status codes follow REST conventions.

Status	Meaning	Common cause
`400`	Bad Request	Missing required field, invalid repo format, empty packages array.
`401`	Unauthorized	Invalid or expired API key.
`403`	Forbidden	Batch audit on free tier (>1 package requires Pro).
`404`	Not Found	No dependencies found in the target GitHub repo.
`429`	Too Many Requests	Rate limit exceeded. Check `Retry-After` header.

429 response body

{
  "error": "Rate limit exceeded. Upgrade to Commit Pro for 10,000 requests/month.",
  "upgrade_url": "https://getcommit.dev/pricing",
  "retry_after": "2026-04-20T00:00:00.000Z"
}

API Reference

Quick Start

Authentication

Rate Limits

Endpoints

Request body

Request body

Request body

Response Schema

Integrations

GitHub Action

MCP Server

Errors

Ready to integrate?