API Documentation
The API has two layers. The public intelligence layer exposes package scans, repo dossiers, advisories, exposure lookups, and ecosystem statistics. The Policy Gate layer consumes the same intelligence for merge-time decisions in CI.
Start here
Public intelligence
Start with /api/scan, /api/report, /api/repo/preview, and /api/advisories. These are the read surfaces the ecosystem can cite, share, and automate against without auth.
When you need enforcement
Policy Gate
Use /api/repo/check for CI decisions and /api/repo/report for repo memory, alerts, and exceptions. Same data, authenticated write path.
Machine-readable discovery
Public intelligence endpoints
No-auth surfaces for package triage, repo reconnaissance, advisory consumption, and ecosystem reporting.
/api/scan?npm={packageName}Package scan
Scan any npm package for install scripts, suspicious URLs, publisher posture, dependency growth, prompt injection patterns, and published source-code risks such as command injection, unsafe eval, hardcoded secrets, and sensitive file access.
curl "https://agentscores.xyz/api/scan?npm=mcp-trust-guard"
/api/report/{package}Package dossier
Return the latest monitored report for a package, including scan history, advisories, and maintainer/disclosure activity when those records exist.
curl "https://agentscores.xyz/api/report/mcp-trust-guard"
/api/repo/preview?repo={owner/repo}Repo dossier preview
Read a public GitHub repo, find its MCP dependencies, scan each package, aggregate capability surface, and compute the same verdict the Policy Gate would return on a pull request.
curl "https://agentscores.xyz/api/repo/preview?repo=redis/RedisInsight"
/api/verdict?npm={packageName}Single allow / warn / block verdict
Return the shortest trust decision for a package. Useful when you want one answer quickly without the full scan payload.
curl "https://agentscores.xyz/api/verdict?npm=mcp-trust-guard"
/api/exposure?npm={packageName}Exposure lookup
Given a compromised package, return monitored MCP servers that depend on it directly using stored dependency snapshots. Built for incident response.
curl "https://agentscores.xyz/api/exposure?npm=axios"
/api/advisories?package={packageName}&severity={level}&limit={n}Advisory feed
Return published advisories when monitored packages change score, risk, or capability surface. Filter by package or severity.
curl "https://agentscores.xyz/api/advisories"
/api/ecosystem/statsEcosystem statistics
Aggregate package counts, risk distribution, capability prevalence, provenance rates, and top movement across the monitored MCP package set.
curl "https://agentscores.xyz/api/ecosystem/stats"
/security/advisories/rss.xmlAdvisories RSS
RSS feed of public advisories. Subscribe in a feed reader or push it into internal monitoring.
https://agentscores.xyz/security/advisories/rss.xml
/api/monitorStart continuous monitoring
Enroll a package in monitoring so the watch and monitor crons keep rescanning it and recording future changes.
curl -X POST "https://agentscores.xyz/api/monitor" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"npm": "mcp-trust-guard",
"email": "security@example.com"
}'/api/monitor?npm={packageName}Monitoring status
Return the latest monitoring snapshot and history for a package that is already enrolled.
curl "https://agentscores.xyz/api/monitor?npm=mcp-trust-guard"
Policy Gate endpoints
Repo-authenticated enforcement surfaces for teams that want merge-time decisions, repo memory, exception handling, and future alerts.
/api/repo/checkPolicy Gate decision
Authoritative CI decision for a repo. Send repo metadata plus MCP packages and AgentScore returns pass/fail, per-package verdicts, applied exceptions, and a decision ID.
curl -X POST "https://agentscores.xyz/api/repo/check" \
-H "Content-Type: application/json" \
-H "X-AgentScore-Key: YOUR_REPO_KEY" \
-d '{
"repo": "owner/repo",
"commit": "abc123",
"branch": "main",
"packages": [
{ "name": "exa-mcp-server", "version": "3.2.0" }
],
"fail_on": "block",
"fail_open": false
}'/api/repo/report?repo={owner/repo}Repo inventory and run history
Return authenticated repo inventory, recent gate runs, stored exceptions, and repo-specific audit history.
curl "https://agentscores.xyz/api/repo/report?repo=owner/repo" \ -H "X-AgentScore-Key: YOUR_REPO_KEY"
/api/repo/alerts?repo={owner/repo}Repo alerts
Return repo-specific alerts created when a monitored package used by that repo worsens later.
curl "https://agentscores.xyz/api/repo/alerts?repo=owner/repo" \ -H "X-AgentScore-Key: YOUR_REPO_KEY"
/api/repo/exceptionsCreate or update exception
Create a repo-specific exception so a warning or block can be approved server-side without editing CI configuration.
curl -X POST "https://agentscores.xyz/api/repo/exceptions" \
-H "Content-Type: application/json" \
-H "X-AgentScore-Key: YOUR_REPO_KEY" \
-d '{
"repo": "owner/repo",
"package": "exa-mcp-server",
"allowed_verdict": "warn",
"reason": "Approved until upstream provenance ships"
}'Scope and limitations
- The package scanner performs static analysis of npm metadata and published source code. It does not execute code or inspect runtime behavior.
- Scores are screening heuristics, not security guarantees.
- Precision is bounded by what regex can express. The public mitigator lineage is at /scanner/precision.
- Repo dossier results are point-in-time readings of public config and dependency state, not a proof of runtime behavior.
Need a guided entry point?
Start with the public surfaces if you are researching risk, assessing a repo, or following advisory drift. Start with the Policy Gate if you already know you want CI enforcement.