> ## Documentation Index
> Fetch the complete documentation index at: https://docs.custoden.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> No sign-up or API key is needed.

Every example below works as-is.

## Check a package

```bash theme={null}
curl https://api.custoden.com/v1/packages/npm/lodash
```

Pin a version with `?version=`:

```bash theme={null}
curl "https://api.custoden.com/v1/packages/pypi/django?version=3.0"
```

Scoped npm packages work with or without encoding the slash:

```bash theme={null}
curl https://api.custoden.com/v1/packages/npm/@types/node
```

The two fields to act on:

| Field | Meaning |
| - | - |
| `verdict` | Trust in the package itself: `malicious`, `suspicious`, `review` or `ok` |
| `risk` | Highest severity across findings and known vulnerabilities |

A package can have `verdict: ok` and `risk: high` when it is legitimate but the requested version has a known vulnerability.

## Check a list of packages

```bash theme={null}
curl -X POST https://api.custoden.com/v1/packages/check \
  -H "Content-Type: application/json" \
  -d '{
    "packages": [
      { "ecosystem": "npm", "name": "express", "version": "4.17.1" },
      { "ecosystem": "pypi", "name": "requests" }
    ]
  }'
```

## Analyze a workflow

Send the YAML file as the request body:

```bash theme={null}
curl -X POST https://api.custoden.com/v1/github/workflows/analyze \
  --data-binary @.github/workflows/ci.yml
```

## Scan recent workflow runs

Check what ran in a public repository over its last 30 runs, including workflows that were later removed:

```bash theme={null}
curl https://api.custoden.com/v1/github/repos/OWNER/REPO/runs
```

## JavaScript

```js theme={null}
const res = await fetch('https://api.custoden.com/v1/packages/npm/left-pad')
const report = await res.json()

if (report.verdict === 'malicious' || report.verdict === 'suspicious') {
  throw new Error(`${report.name}: ${report.findings[0].title}`)
}
```

## Python

```python theme={null}
import requests

report = requests.get("https://api.custoden.com/v1/packages/pypi/requests").json()

for finding in report["findings"]:
    print(finding["severity"], finding["title"])
```

## Next steps

* [Rate limits](https://docs.custoden.com/getting-started/rate-limits.md)
* [Errors](https://docs.custoden.com/getting-started/errors.md)
* [Block risky packages in CI](https://docs.custoden.com/guides/block-risky-packages-in-ci.md)
* [Scan workflows on pull requests](https://docs.custoden.com/guides/scan-workflows-on-pull-requests.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.