📡 API Reference

Inspect dependency maintenance-health before a human or AI agent recommends, adds, or audits a package.

Base URL

https://isitalive.dev

Authentication

Authentication is optional for project checks and badges. It is required for the manifest audit endpoint. Use an API key for all repos, or GitHub Actions OIDC for public-repo audits:

# Add to any request
Authorization: Bearer sk_your_api_key

Agent Quick Start

Start from package names when possible. Add X-IsItAlive-Client so aggregate analytics can distinguish agent and client integrations. This header is not authentication and should not contain secrets.

# Package-first check
curl -s https://isitalive.dev/api/check/package/npm/react \
  -H "X-IsItAlive-Client: codex/1.0" | jq

# Repo-first check when you already know owner/repo
curl -s https://isitalive.dev/api/check/github/vercel/next.js \
  -H "X-IsItAlive-Client: codex/1.0" | jq

# Manifest audit; retry after retryAfterMs when complete is false
curl -s -X POST 'https://isitalive.dev/api/manifest?include=drivers,metrics,signals' \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "X-IsItAlive-Client: codex/1.0" \
  -H "Content-Type: application/json" \
  -d '{"format":"package.json","content":"<package.json contents>"}' | jq

Endpoints

Check Package Maintenance

GET /api/check/package/{ecosystem}/{packageName}

Resolve an npm package or Go module to GitHub, then return the normal maintenance-health score with package context attached. Use this when an agent or human starts from a dependency name such as react, @types/node, or golang.org/x/crypto. Query fallback: /api/check/package/{ecosystem}?name=....

ParameterTypeDescription
ecosystemrequired string npm or go
packageNamerequired string Package name or Go module path. Use URL encoding when needed.
include string Optional. Use metrics to include normalized raw measurements and sampling metadata.

Example Request

# Check an npm package's underlying GitHub repo
curl https://isitalive.dev/api/check/package/npm/react \
  -H "X-IsItAlive-Client: codex/1.0"

Resolve Package Only

GET /api/resolve/{ecosystem}/{packageName}

Return only the package-to-GitHub mapping, including package, github, and resolvedFrom. Query fallback: /api/resolve/{ecosystem}?name=....

Batch Check Dependencies

POST /api/check/batch

Authenticated batch endpoint for up to 200 mixed package descriptors, package URLs (purls), and GitHub repositories. Optional policy fields return per-dependency pass, warn, fail, or skipped outcomes plus an aggregate policyVerdict.

Batch Example

# Check mixed package and purl inputs with policy
curl -X POST https://isitalive.dev/api/check/batch \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"kind":"package","ecosystem":"npm","name":"react"},{"kind":"purl","purl":"pkg:golang/golang.org/x/crypto"}],"policy":{"failBelowScore":60,"failOnUnresolved":true}}'

Check Project Maintenance

GET /api/check/{provider}/{owner}/{repo}

Returns a 0-100 maintenance-health score, verdict, methodology metadata, top drivers, and signal evidence for any GitHub repository. Use it before recommending, adding, or automating a dependency. Add ?include=metrics when you need normalized raw measurements.

ParameterTypeDescription
providerrequired string Source code hosting provider. Currently: github
ownerrequired string Repository owner or organization (e.g. vercel)
reporequired string Repository name (e.g. next.js)
include string Optional. Use metrics to include normalized raw measurements and sampling metadata.

Example Request

# Check a project's maintenance-health
curl https://isitalive.dev/api/check/github/vercel/next.js \
  -H "X-IsItAlive-Client: codex/1.0"

# Add ?include=metrics only when raw normalized measurements are needed
curl https://isitalive.dev/api/check/github/vercel/next.js?include=metrics \
  -H "X-IsItAlive-Client: codex/1.0"

Example Response

{
  "project": "github/vercel/next.js",
  "provider": "github",
  "score": 92,
  "verdict": "healthy",
  "checkedAt": "2026-03-20T10:00:00Z",
  "cached": true,
  "methodology": {
    "version": "2026-03-30-agent-ready-v1",
    "scoreType": "maintenance-health",
    "url": "https://isitalive.dev/methodology"
  },
  "drivers": [
    {
      "signal": "lastCommit",
      "direction": "positive",
      "summary": "The default branch received a recent commit."
    }
  ],
  "signals": [
    {
      "name": "lastCommit",
      "label": "Last Commit",
      "value": "2 days ago",
      "score": 100,
      "weight": 0.25,
      "measurement": "direct",
      "source": "defaultBranchRef.target.history(first: 1)"
    }
  ],
  "metrics": {
    "lastCommitAgeDays": 2,
    "prSampleSize": 20,
    "ciDataSource": "actions-runs"
  },
  "cache": {
    "status": "l2-hit",
    "tier": "free",
    "ageSeconds": 3600,
    "nextRefreshSeconds": 82800
  }
}

Response Fields

projectFully qualified identifier: provider/owner/repo
scoreWeighted maintenance-health score from 0 (unmaintained) to 100 (healthy)
verdictHuman-readable maintenance-health verdict based on score (see table below)
checkedAtISO 8601 timestamp of when data was fetched from the provider
cachedWhether this result was served from cache
methodologyVersioned description of the scoring algorithm, including scoreType: "maintenance-health"
drivers[]Top positive or negative reasons the score moved, optimized for quick agent reasoning
signals[]Stable camelCase signals with score, weight, measurement type, and provider source. Canonical names: lastCommit, lastRelease, prResponsiveness, issueStaleness, recentContributors, busFactor, ciActivity, starsTrend
metricsOptional normalized raw values and sample sizes, returned when you pass include=metrics
overrideReasonIf present, explains why the score was overridden (e.g. archived repo)
cache.nextRefreshSecondsSeconds until data refreshes — use this to schedule your next poll

Verdicts

ScoreVerdictMeaning
80–100🟢 healthyHealthy maintenance-health signal
60–79🟡 stableStable maintenance-health signal
40–59🟠 degradedDegraded maintenance-health signal
20–39🔴 criticalCritical maintenance-health signal
0–19⚫ unmaintainedUnmaintained maintenance-health signal
This is a maintenance-health score only. It helps humans and AI agents judge maintainer activity and project durability before choosing dependencies. It is not a security, license, or compliance verdict.

Audit Dependency Manifest

POST /api/manifest

Upload a package.json, package-lock.json, pnpm-lock.yaml, yarn.lock, go.mod, or go.sum and get a scored maintenance-health report for every dependency. Alias: /api/check/manifest. Authentication is required: API key for any repo, or GitHub Actions OIDC for public repos. Add ?include=drivers,metrics,signals for richer agent output.

Request Body

format"package.json", "package-lock.json", "pnpm-lock.yaml", "yarn.lock", "go.mod", or "go.sum"
contentRaw manifest file content (max 512KB)
policyOptional policy thresholds for score, unresolved deps, confidence, dev deps, and release age
maxAgeSecondsOptional best-effort freshness target; stale cached data is flagged with stale_data

Query Parameters

includeOptional comma-separated extras. Supported values: drivers, metrics, signals.

Example Request

# Audit a go.mod file with rich agent output
curl -X POST 'https://isitalive.dev/api/manifest?include=drivers,metrics,signals' \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "X-IsItAlive-Client: codex/1.0" \
  -H "Content-Type: application/json" \
  -d '{"format":"go.mod","content":"<go.mod contents>"}'

Example Response

{
  "auditHash": "7da0c591f32d...",
  "complete": true,
  "scored": 262,
  "total": 262,
  "methodology": { "version": "2026-03-30-agent-ready-v1", "scoreType": "maintenance-health" },
  "summary": { "healthy": 53, "avgScore": 52, ... },
  "dependencies": [
    {
      "name": "github.com/zitadel/zitadel",
      "github": "zitadel/zitadel",
      "resolvedFrom": "go.mod require",
      "score": 100,
      "verdict": "healthy",
      "checkedAt": "2026-03-20T10:00:00Z",
      "dev": false,
      "drivers": [ ... ],
      "metrics": { ... },
      "signals": [ ... ]
    }
  ]
}

Audit Response Fields

auditHashSHA-256 of manifest content — also returned as ETag header
completetrue if all deps scored. If false, call again after retryAfterMs
retryAfterMsSuggested wait in ms before calling again (only when incomplete)
methodologySame versioned scoring metadata returned by /api/check
dependencies[]Per-dependency results: name, version, github, score, verdict, dev, unresolvedReason, resolvedFrom, checkedAt, identity, resolution, state, healthVerdict, dataFreshness, riskFlags, policy, and optional drivers/metrics/signals when requested
Retry logic: If complete is false, call the same endpoint again after retryAfterMs. The cache fills progressively — each call is faster.

Unresolved deps: Dependencies not on GitHub get verdict: "unresolved" with a reason (e.g. gitlab_not_supported_yet, no_github_repo).

Get SVG Badge

GET /api/badge/{provider}/{owner}/{repo}

Returns an SVG maintenance-health badge for README embedding. Edge-cached for 24 hours.

# Markdown
[![Is It Alive?](https://isitalive.dev/api/badge/github/YOUR_ORG/YOUR_REPO)](https://isitalive.dev/github/YOUR_ORG/YOUR_REPO)

# HTML
<a href="https://isitalive.dev/github/YOUR_ORG/YOUR_REPO">
  <img src="https://isitalive.dev/api/badge/github/YOUR_ORG/YOUR_REPO" alt="Is It Alive?">
</a>

Rate Limits

IsItAlive is free to use for public maintenance-health checks. Infrastructure limits apply. Freshness is the same for anonymous and authenticated requests; request limits vary by authentication state.

AccessRate LimitFresh WindowStale WindowL1 Cache TTL
Anonymous5 req/min24 hours48 hours24 hours
API key or GitHub OIDC50 req/min24 hours48 hours24 hours
Rate limit headers are included with every response:
X-RateLimit-Limit, X-RateLimit-Tier (free)

Cache Statuses

StatusMeaning
l1-hitServed from the Worker Cache API in the current datacenter.
l2-hitServed from Workers KV while still inside the fresh window.
l2-staleServed from stale KV data while background revalidation runs.
l2-stale-degradedUpstream provider is unavailable; served from cached data past its normal stale window. The response includes degraded: true and is not re-cached.
l3-missFetched live from the provider and freshly scored.

Error Responses

StatusMeaning
400Invalid or unsupported provider
401Authentication required (manifest audit endpoint)
404Repository not found on GitHub
429Rate limit exceeded — check Retry-After header

Machine-Readable Specs

openapi.jsonOpenAPI 3.1 specification
llms.txtLLM-friendly API description
ai-plugin.jsonAI agent plugin manifest