API Documentation

Everything you need to integrate DepHealth into your workflow.

1 Quick Start

Get your API key and start checking packages:

# Check a package
curl -H "X-API-Key: YOUR_KEY" \
  https://api.dephealth.laranjo.dev/v1/packages/npm/express

2 Authentication

Include your API key in the X-API-Key header:

X-API-Key: dh_your_api_key_here

Need an API key? Request one here

3 Base URL

https://api.dephealth.laranjo.dev/v1

4 Endpoints

GET /v1/health

Health check endpoint. No authentication required.

Example

Request 
curl https://api.dephealth.laranjo.dev/v1/health
Response 
{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2026-01-07T20:00:00.000Z"
}
GET /v1/packages/npm/{name} Auth Required

Get health score and details for a single npm package.

Parameters

name string Package name (URL-encoded for scoped packages)

Example

Request 
curl -H "X-API-Key: YOUR_KEY" \
  https://api.dephealth.laranjo.dev/v1/packages/npm/express
Response 
{
  "package": "express",
  "ecosystem": "npm",
  "health_score": 83.5,
  "risk_level": "LOW",
  "abandonment_risk": {
    "probability": 3.5,
    "time_horizon_months": 12,
    "components": {
      "bus_factor_risk": 0.4,
      "inactivity_risk": 0,
      "adoption_risk": 10,
      "release_risk": 9.4
    }
  },
  "components": {
    "maintainer_health": 100,
    "evolution_health": 86.5,
    "community_health": 73.7,
    "user_centric": 69.3,
    "security_health": 72.5
  },
  "signals": {
    "weekly_downloads": 37871062,
    "dependents_count": 0,
    "stars": 68517,
    "days_since_last_commit": 0,
    "commits_90d": 28,
    "active_contributors_90d": 11,
    "maintainer_count": 5,
    "is_deprecated": false,
    "archived": false,
    "openssf_score": 7.5,
    "true_bus_factor": 4,
    "bus_factor_confidence": "HIGH"
  },
  "openssf_checks": {
    "summary": {
      "Branch-Protection": {"score": 8, "status": "pass"},
      "Security-Policy": {"score": 9, "status": "pass"},
      "Code-Review": {"score": 5, "status": "partial"}
    },
    "all_checks": [...]
  },
  "confidence": {
    "score": 87.5,
    "level": "HIGH"
  }
}
POST /v1/scan Auth Required

Scan multiple packages from a package.json file.

Request Body

{
  "dependencies": {
    "express": "^4.18.0",
    "lodash": "^4.17.21"
  }
}

// OR pass the entire package.json content:
{
  "content": "{ \"dependencies\": {...} }"
}

Example

Request 
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dependencies": {"express": "^4.0.0"}}' \
  https://api.dephealth.laranjo.dev/v1/scan
Response 
{
  "total": 1,
  "critical": 0,
  "high": 0,
  "medium": 0,
  "low": 1,
  "packages": [
    {
      "package": "express",
      "ecosystem": "npm",
      "health_score": 83.5,
      "risk_level": "LOW",
      "abandonment_risk": {
        "probability": 3.5,
        "time_horizon_months": 12,
        "risk_factors": []
      },
      "components": {
        "maintainer_health": 85.2,
        "user_centric": 92.1,
        "evolution_health": 78.4,
        "community_health": 81.3,
        "security_health": 72.5
      }
    }
  ],
  "not_found": []
}
GET /v1/usage Auth Required

Get your current API usage and limits.

Example

Request 
curl -H "X-API-Key: YOUR_KEY" \
  https://api.dephealth.laranjo.dev/v1/usage
Response 
{
  "tier": "free",
  "usage": {
    "requests_this_month": 42,
    "monthly_limit": 5000,
    "remaining": 4958,
    "usage_percentage": 0.8
  },
  "reset": {
    "date": "2026-02-01T00:00:00+00:00",
    "seconds_until_reset": 2087010
  }
}

5 Risk Levels

LOW
80-100
Package is healthy and well-maintained
MEDIUM
60-79
Some concerns, monitor for changes
HIGH
40-59
Significant risk factors present
CRITICAL
0-39
Serious concerns, consider alternatives

6 Rate Limits

Tier Requests/Month Price
Free 5,000 $0
Starter 25,000 Coming soon
Pro 100,000 Coming soon
Business 500,000 Coming soon

Rate limit headers are included in every response:

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4958

7 Error Handling

All errors follow a consistent format:

{
  "error": {
    "code": "error_code",
    "message": "Human-readable error message"
  }
}
Status Code Description
401 invalid_api_key Missing or invalid API key
404 package_not_found Package not in our database
429 rate_limit_exceeded Monthly limit reached